В корпоративных вики до сих пор можно встретить разделы, которые не обновлялись больше года. К примеру, в них по-прежнему фигурирует Apache Hive, хотя команда уже работает на Trino, а часть описанных сервисов давно выведена из эксплуатации. Разработчик открывает такую страницу, быстро закрывает и идет уточнять информацию у коллег. Документация остается невостребованной.
Традиционные форматы — вики, PDF, Word — плохо выдерживают темп современной разработки. Нет прозрачной истории изменений, ревью часто формальное, публикация требует ручных действий. Материалы устаревают, доверие к ним падает, и проще спросить эксперта, чем искать ответ в документации. Она сохраняет ценность только тогда, когда дает быстрый и точный ответ на конкретный вопрос. В остальных случаях документация перестает быть рабочим инструментом.
Чтобы изменить ситуацию, актуализацию документации нужно встроить непосредственно в процесс разработки. Тогда к моменту выхода функциональности в промышленную эксплуатацию код и его описание будут согласованы.
Документация как часть конвейера разработки
Раньше документацию пытались поддерживать отдельными усилиями — результат редко оказывался устойчивым. Более эффективный подход — поддерживать согласованность кода и описания на всех этапах работы над функциональностью.Аналитик фиксирует требования и сценарии. Разработчик реализует изменения и одновременно обновляет соответствующую документацию. Специалист по тестированию проверяет поведение системы и при необходимости уточняет описание. В CI/CD выполняются проверки актуальности: при расхождении между кодом и документацией пайплайн сигнализирует о необходимости корректировки. К моменту вывода функциональности в промышленную эксплуатацию реализация и ее описание уже синхронизированы. Актуализация происходит по ходу работы, а не после ее завершения.
Docs as Code: документация рядом с кодом
Один из рабочих способов поддерживать документацию в актуальном состоянии, к которому мы в итоге пришли — подход Docs as Code. Документы размещают в тех же репозиториях, что и код, пишут в Markdown, проводят ревью через pull request и публикуют автоматически средствами CI/CD.При изменении поведения сервиса инженер сразу правит файл с описанием. Изменения проходят ревью и после слияния автоматически появляются на сайте.
Такой подход дает несколько преимуществ:
● документация меньше отстает от кода;
● история изменений остается прозрачной;
● ревью текста становится частью стандартного процесса проверки;
● публикация не требует дополнительных ручных действий;
● материалы обновляются, пока контекст задачи еще свеж.
В командах, последовательно применяющих этот подход, документация перестает быть отдельной задачей и становится частью повседневной работы. Для публикации часто используют генераторы статических сайтов — MkDocs, Docusaurus и пр. Они превращают Markdown-файлы в удобный ресурс с поиском и навигацией.
Организация хранения знаний
Когда ресурсов на поддержку вики-систем недостаточно, целесообразнее размещать документацию ближе к коду:● файлы Markdown в репозитории проекта;
● README в корневых и ключевых директориях;
● генераторы статической документации (MkDocs, Docusaurus и аналогичные решения).
В Газпромбанке документация из Bitbucket и Git централизованно поступает в платформу Backstage. Система автоматически актуализирует сведения и упрощает поиск информации, а также навигацию между системами, продуктами и компонентами. Обновление происходит в рамках тех же процессов и с использованием тех же инструментов, что и работа с кодом.
Инструменты и технологии
В банке для создания и управления документацией применяются следующие инструменты и технологии:● Git — система контроля версий, которая позволяет отслеживать изменения в документации и организовывать совместную работу.
● Backstage — платформа управления документацией, упрощающая поиск информации и навигацию между системами, продуктами и компонентами. Используются внутренняя документация проекта и стандарт описания catalog-info.yaml.
● Markdown — язык разметки, обеспечивающий простоту написания и форматирования текстов.
● MkDocs — инструмент генерации статической документации, позволяющий публиковать материалы в удобном HTML-формате.
● IDEA — интегрированная среда разработки, поддерживающая работу как с кодом, так и с документацией.
● AsyncAPI — спецификации для описания RESTful и асинхронных API, которые помогают стандартизировать взаимодействие компонентов и упрощать интеграцию.
Когда актуализация описаний становится естественной частью работы с кодом, документация перестает быть формальным артефактом. Она начинает выполнять свою основную задачу — давать команде точную и своевременную информацию.
