Документация как код. Инструменты

Это продолжение статьи, выходившей на прошлой неделе. Рекомендую сначала ознакомиться с ней.

Давайте подробнее об инструментах, что нужно использовать, чтобы реализовать подход Docs as a Code.

0) У аналитиков должен быть доступ к коду. Очевидный и главный пункт. Если ИБ считает, что код вам видеть не положено, то дальнейший текст не имеет смысла.

1) IDE. Подойдет любая, но мы работали с продуктами JetBrains. Выбирайте ту, в которой пишут разрабы. Кстати, недавно зарелизилась IDE для документации – Writeside. На боевых проектах не пробовал, но выглядит интересно.

2) Описание. Дальнейшие шаги завязаны на расширениях для IDE, поскольку не все поддерживается из коробки. Мы использовали AsciiDoc для текстового описания. Конкретно этот плагин. Также прикладываю синтаксис. В качестве аналога можно использовать Markdown. Он работает без дополнительных расширений.

3) Диаграммы. Использовали PlantUML. Расширение доступно здесь. Синтаксис можно изучить тут. В качестве альтернативы рассмотрите возможность использования Mermaid.

4) API. Для описания апишек использовали формат OpenAPI. Он также поддерживается без дополнительных расширений. Но для удобства использовал плагин позволяющий быстро перемещаться по разделам. Уроков по использования Swagger очень много, вот один из них.

Как это работало? При написании документации аналитик создавал ветку, где добавлял папку “docs” в корень репозитория, в ней хранились необходимые файлы с расширениями .adoc, .puml и .yaml соответственно. Как только описание было завершено, разработчик начинал писать код в той же ветке. Наконец, дока и код одновременно сливались в мастер.

Стало ли понятнее? Остались ли вопросы? Пишите в комментариях.