Протягом останніх кількох років інженери Pinterest працювали над впровадженням підходу Docs-as-Code в масштабах усієї організації. Завдяки використанню тих самих інструментів і процесів для коду й документації компанії вдалося підвищити загальну якість документації й задоволеність команд. Це також сприяло формуванню нової культури документації: зросла співпраця, покращився контроль якості, пошук і доступність. Про це йдеться в матеріалі InfoQ.
Підхід Docs-as-Code передбачає ставлення до документації як до коду. Це означає використання мов розмітки (наприклад, Markdown або Asciidoc), керування файлами за допомогою систем контролю версій, застосування CI/CD для перевірки й публікації, а також автоматичне створення фінального HTML-сайту.
Pinterest стандартизував використання Markdown і Git, інтегрував документацію в пайплайни рев’ю та деплойменту, а також створив власні інструменти для керування документацією, включаючи підтримку метаданих, шаблонів і пошуку.
«Ми відчували, що впровадження Docs-as-Code допоможе вирішити наші проблеми з документацією. Ми створили систему, яка заохочує до якісної документації просто завдяки самому процесу», — зазначили в компанії.
Цей підхід дозволив подолати низку труднощів із попередніми процесами: складність внесення змін, тривалі цикли зворотного зв’язку, обмежений доступ зацікавлених сторін до рев’ю та низьку виявлюваність документації, яка зберігалась окремо від коду. Ще однією проблемою було використання WYSIWYG-редакторів, які поєднували стиль і зміст — замість чіткого розділення.
Крім того, Docs-as-Code підвищив ймовірність актуальності документації та дозволив на ранніх етапах виявляти проблеми з дизайном або зручністю API.
«Розвиваючи документацію разом із кодом, ми завчасно бачимо користувацький досвід розробника. Проблеми в API часто проявляються саме під час написання документації», — кажуть у Pinterest.
Компанія створила внутрішній інструмент Pinterest Docs (PDocs), який дозволяє хостити документацію з різних репозиторіїв в одному місці:
«Ми хотіли статичний генератор сайтів, який би автоматично збирав документацію з різних шляхів і репозиторіїв і формував централізований сайт».
PDocs сканує всі репозиторії на наявність файлів pdocs.yaml, де зазначено, які Markdown-файли слід обробити в HTML. CLI-інструмент спрощує роботу: дозволяє створювати проєкти з шаблонною конфігурацією та запустити live-reload сервер для попереднього перегляду під час розробки.
За внутрішніми опитуваннями, досвід написання та перегляду документації в PDocs значно перевищує той, що був із wiki-інструментами, які використовувалися раніше.
Ключовим чинником успіху стала утиліта-конвертер з wiki до PDocs, яка лише за два місяці забезпечила 20% зростання кількості проєктів — понад 140. Pinterest планує й надалі розвивати інструмент, покращуючи UX і функції для спільної роботи.
Підхід Docs-as-Code активно використовують також великі організації, зокрема AWS, уряд Великої Британії та GitHub. Для тих, хто хоче розпочати впровадження цієї практики, чудовим ресурсом є сайт Write the Docs.
Читайте також на ProIT: Топ-5 сервісів автоматизації email розсилок. ProIT зібрав топ-5 зручних сервісів для e-mail розсилок. Вони допоможуть легко надсилати листи клієнтам і повідомляти про знижки, акції або новини.
Підписуйтеся на ProIT у Telegram, щоб не пропустити жодної публікації!
