Документация как код
На прошлой работе внедрили офигенную практику – вести документацию как код (docs as a code). Перед нами стояла задача перетащить всю доку из Confluence в Git, сделав удобно всем. Спойлер, получилось не совсем гладко, но давайте по порядку.
Я работал в команде интеграций на бэке. Мы пилили интеграционные адаптеры с различными банками и МФО. Процесс выглядел так: адаптер слушает определенную очередь, получает сообщение, преобразовывает его и отправляет вовне. В рамках адаптера содержится несколько методов, от одного до нескольких десятков. Это чисто техническая история, мы не взаимодействовали с фронтом и не описывали его.
Ситуация “As-Is”. Под каждый адаптер есть статья в Confluence, где пошагово расписан процесс: какую очередь слушаем, куда отправляем результат, в какую очередь складываем ответ, пример/описание входящего/исходящего сообщения, и другая техническая информация. Если методов было много, то прикладывали ссылку на draw.io с Sequence Diagram.
Что же получилось? Для текстового описания выбрали AsciiDoc. У него понятный синтаксис, а главное, он корректно отображается в Confluence. Для того, чтобы не делать двойную работу, вся документация велась в Git, а в Confluence указывались ссылки на репозитории.
Помимо AsciiDoc стали использовать PlantUML. Он сильно ускорил процесс «отрисовки» диаграмм, ведь теперь аналитик работает с текстом, а графическое расположение формируется автоматически. Плюс, для каждого метода стали моделировать Class Diagram. В перспективе из них разработчики могли бы генерировать классы.
Наконец, шлифанули это все OpenAPI. Ранее аналитик прописывал параметры и ограничения запроса, а разработчик дублировал эту работу в коде. OpenAPI позволял делать это один раз – аналитик формирует спеку, а разработчик из нее генерирует код. Искренне не понимаю, почему всю доку API не делают именно в формате OpenAPI, ведь это наглядный и понятный стандарт.
В идеальной картине мы видели следующие плюсы:
- Всегда актуальная документация. Ведь она изменяется только вместе с кодом.
- Ускоренная разработка. Ведь часть работы уже выполнил аналитик.
- Прокаченные аналитики. Ведь им нужно освоить несколько новых инструментов.
Реальность оказалось суровее. После ухода тимлида (мощнейший эксперт, безумно рад, что нам удалось поработать вместе) инициативу стало почти невозможно толкать. В работе использовалось только Ascii описание, а Puml и Swagger никто не использовал. Соседние команды смотрели на нас как на сумасшедших – «ведь аналитикам придется делать столько дополнительной работы». А бизнес говнялся, ведь им было неудобно смотреть рендеринг репозиториев Git в Confluence.
По итогу, из запланированного взлетела только часть. Несмотря на это, каждый раз, когда я говорил на собеседованиях, что веду документацию в Git, в ответ получал только «мое почтение».
А как обстоят дела с докой на работе у вас?
На прошлой работе внедрили офигенную практику – вести документацию как код (docs as a code). Перед нами стояла задача перетащить всю доку из Confluence в Git, сделав удобно всем. Спойлер, получилось не совсем гладко, но давайте по порядку.
Я работал в команде интеграций на бэке. Мы пилили интеграционные адаптеры с различными банками и МФО. Процесс выглядел так: адаптер слушает определенную очередь, получает сообщение, преобразовывает его и отправляет вовне. В рамках адаптера содержится несколько методов, от одного до нескольких десятков. Это чисто техническая история, мы не взаимодействовали с фронтом и не описывали его.
Ситуация “As-Is”. Под каждый адаптер есть статья в Confluence, где пошагово расписан процесс: какую очередь слушаем, куда отправляем результат, в какую очередь складываем ответ, пример/описание входящего/исходящего сообщения, и другая техническая информация. Если методов было много, то прикладывали ссылку на draw.io с Sequence Diagram.
Что же получилось? Для текстового описания выбрали AsciiDoc. У него понятный синтаксис, а главное, он корректно отображается в Confluence. Для того, чтобы не делать двойную работу, вся документация велась в Git, а в Confluence указывались ссылки на репозитории.
Помимо AsciiDoc стали использовать PlantUML. Он сильно ускорил процесс «отрисовки» диаграмм, ведь теперь аналитик работает с текстом, а графическое расположение формируется автоматически. Плюс, для каждого метода стали моделировать Class Diagram. В перспективе из них разработчики могли бы генерировать классы.
Наконец, шлифанули это все OpenAPI. Ранее аналитик прописывал параметры и ограничения запроса, а разработчик дублировал эту работу в коде. OpenAPI позволял делать это один раз – аналитик формирует спеку, а разработчик из нее генерирует код. Искренне не понимаю, почему всю доку API не делают именно в формате OpenAPI, ведь это наглядный и понятный стандарт.
В идеальной картине мы видели следующие плюсы:
- Всегда актуальная документация. Ведь она изменяется только вместе с кодом.
- Ускоренная разработка. Ведь часть работы уже выполнил аналитик.
- Прокаченные аналитики. Ведь им нужно освоить несколько новых инструментов.
Реальность оказалось суровее. После ухода тимлида (мощнейший эксперт, безумно рад, что нам удалось поработать вместе) инициативу стало почти невозможно толкать. В работе использовалось только Ascii описание, а Puml и Swagger никто не использовал. Соседние команды смотрели на нас как на сумасшедших – «ведь аналитикам придется делать столько дополнительной работы». А бизнес говнялся, ведь им было неудобно смотреть рендеринг репозиториев Git в Confluence.
По итогу, из запланированного взлетела только часть. Несмотря на это, каждый раз, когда я говорил на собеседованиях, что веду документацию в Git, в ответ получал только «мое почтение».
А как обстоят дела с докой на работе у вас?