Docs as Code: Документация в DevOps, интеграция, инструменты и мотивация

Docs as Code: так тоже бывает

💡🧠Автотесты кое-как пережили, теперь новый вызов. Сегодня хочу рассказать о том, как я познакомилась с Docs as Code и что из этого может получиться.

Вообще на поиск вариантов как быть с документацией меня натолкнули две вещи: завершающая стадия одного проекта и комментарий в Сетке одного тимлида на мой пост. Мне подсказали, что неплохо бы научиться создавать документацию параллельно разработке. И что есть Docs as Code. Сила соцсетей!

💔Когда я спросила разработчиков одного из проектов, знают ли они что это, тимлид сказал “не знаю”, а разработчик -“ой, давайте только без этого” и выключил камеру. Разбираемся, хорошо или плохо - составлять документацию как код. И вообще - что это такое. Мне интересно, а вам?

Docs as Code — это методология, при которой документация создается, управляется и версионируется так же, как и исходный код приложения. Она хранится в системах контроля версий (любимый Git!), может проходить через этапы ревью, автоматического тестирования, и даже CI/CD, что приближает процесс работы с документацией к тому, как разрабатываются и выпускаются сами продукты.
Почему это классно:

💗Документация находится рядом с кодом в репозитории. Разработчики и технические писатели могут совместно работать над текстом и кодом, делая документацию более актуальной и синхронизированной с версией продукта.

💗Docs as Code позволяет отслеживать изменения в документации, возвращаться к предыдущим версиям и видеть, кто и что изменил.

💗Благодаря интеграции с CI/CD, можно автоматически проверять документацию на синтаксические ошибки, форматирование, и даже запускать тесты, которые проверяют корректность примеров кода в документации.

💗Платформы, такие как GitHub или GitLab, позволяют легко принимать пул-реквесты, оставлять комментарии и проводить ревью изменений в документации, так же как и в коде.

💗Весь процесс редактирования документации становится прозрачным для команды. Все могут увидеть, как и когда обновлялись документы, и это помогает поддерживать документацию в актуальном состоянии.

💎💎💎Инструменты для Docs as Code

✍️Git: для контроля версий документации.
✍️MkDocs и Sphinx: для генерации статических сайтов из документации.
✍️Swagger: для автоматической генерации документации API.
✍️JSDoc, Doxygen: для генерации документации на основе комментариев в коде.
✍️Vale, MarkdownLint: для проверки стиля и качества документации.

Есть много причин, почему разработчики могут быть не заинтересованы в использовании этого подхода. Мне кажется, главная - сложность интеграции документации в DevOps процессы.

Хотя это мощный инструмент для интеграции документации в DevOps, его реализация может потребовать дополнительных усилий на начальных этапах. Настройка пайплайнов CI/CD для автоматической генерации и тестирования документации требует времени, а также дополнительного изучения инструментов. Для команды, которая никогда не работала с таким подходом, это может казаться сложной и затратной задачей.

🚀🚀🚀Как мотивировать разработчиков к использованию Docs as Code?

Я думаю, что нужно попробовать идти через автоматизацию и использование удобных инструментов для документирования. Но в любом случае, подозреваю что это overskill и тут должна быть еще мотивация интересом. Для руководителя проекта ключевыми задачами тут станут поддержка команды, автоматизация и стандартизация процессов. Важно начать с малого, обучить команду и постепенно адаптировать инструменты и практики, чтобы они стали неотъемлемой частью DevOps-процессов.

В долгосрочной перспективе, несмотря на сложности на начальных этапах, Docs as Code помогает сократить время на поддержку документации и делает её полезным инструментом для всех участников команды.

#IT