Частая практика многих компаний — не включать документирование в артефакты ПО. Если заглянуть в прошлое, то станет ясно, что до появления роли DevOps, мы испытывали трудности с поставкой версий ПО. Этим занимались сами программисты или администраторы, что в конечном итоге вызывало проблемы в процессе передачи, конфигурирования и развертывания ПО.
Похожая ситуация сложилась и с документацией на программное обеспечение, так как во многих компаниях это до сих пор остается болезненным вопросом.
Документацию следует делить на разные виды, что-то обязательно для написания, что-то опционально:
- Техническое задание, функциональное описание, сценарии использования;
- Техническое решение (включает архитектуру, описание компонентов, спецификация api, структур данных, документацию по развертыванию и т.д.);
- Документация внутри кода;
- План и сценарии тестирования;
- Документация для конечного пользователя.
Документацию, также, как и программный код, следует проверять на качество. Мы пропагандируем подход, когда проверяем качество на каждом этапе разработки продукта. Т.е., на уровне разработки ПО, это codereview и покрытие кода тестами, на уровне функционального тестирования, это review покрытия кода функциональными или автотестами, на уровне аналитики, это review документации и архитектурного решения, review работы техписателей — пользовательская документация и на других уровнях.
В условиях реализации больших проектов, при наличии множества подсистем и компонентов, повышается сложность проведения анализа и проверок, требуются такие инструменты управления документацией и подходы к управлению, при которых мы получим единые правила работы с документацией, описание компонентов системы, механизмы управления изменениями, механизмы кросс-компонентного описания и механизмы сборки и тестирования получаемых артефактов.
При создании документации важно придерживаться необходимого уровня информационной насыщенности. Соблюдение такого условия с трудом поддается проверке из-за субъективности в данном процессе. Надо принимать во внимание следующие факторы: кем является клиент (внутренний или внешний) и какого именно объема информации он ожидает. Большинство программистов, как потребители контента, такого как ТЗ или технический проект, не читают досконально документацию, особенно, если в ней много воды, поэтому важно отразить в ней минимально необходимый объем воспринимаемой информации. Как правило, это схемы, диаграммы, интерфейсы и краткое описание. С пользовательской документацией — все то же самое, но объём информации о функциональности должен быть больше.
Давайте вспомним об основной задаче DevOps: автоматизация процесса поставки ПО. Этот процесс должен быть согласован с разработчиками и группами внедрения и сопровождения эксплуатируемого ПО.
В таком случае задача DocOps — автоматизировать процесс поставки документации между фазами разработки проекта, согласованный с участниками процесса. Какие проблемы мы можем решить используя подход DocOps:
- Построение общей структуры документации;
- Общие механизмы работы с требованиями;
- Кросс проектная трассировка требований;
- Разработка общих подходов к использованию принятых схем, таких, как UML-схемы — диаграмма последовательностей, диаграмма развертывания, компонентная схема;
- Разграничение функциональных зон ответственности;
Прочее.
Для технической документации, например, для описания интерфейсов API, часто используется язык разметки Markdown. Подобные языки позволяют генерировать исходную документацию одним пакетом или веб сайтом. Этот подход — docs as code используют в больших проектах с множеством пересекающихся компонентов и сервисов. Например, документация Microsoft (docs.microsoft.com) реализована по такому же принципу.
Преимущества при использовании такого подхода:
- Общий инструмент и общие правила документирования;
- Возможность автосборки вместе с исходными кодами;
- Версионность документации;
- Единое пространство, база знаний проекта;
- Низкий порог вхождения для новых членов команды;
- Снижение bus factor ключевых сотрудников;
- Экономия рабочего времени команды и фокусировка на проекте;
- Общее информирование по результатам внесения изменений.
Разметка отличный инструмент для порождения культуры документирования. Выбрав инструмент автосборки документации, необходимо продумать структуру портала, спроектировать информационную архитектуру данных, определить структуру контента, общие внутренние нотации для, например, отрисовки схем данных, определить шаблоны документов и частных элементов, компонентов, настроить процесс ci/cd и интегрировать документацию в существующие процессы работы с кодом.
Один из популярных инструментов для создания онлайн-документации — Docusaurus, реализован в Facebook, — пример инструмента, который поддерживает Markdown, он подкачивает ваши файлы и генерирует портал, который можно использовать как внутри компании, так и для внешних клиентов.
Вы можете использовать любой инструмент. Но при этом необходимо понимать самое главное: процесс документирования должен быть реализован с использованием единой, общепринятой нотации.
В заключение отмечу что нужно помнить, что отсутствие документации на программный код, это не ошибка программистов, это, как правило, ошибка в процессах разработки, ошибка управленческого характера, которую нужно решать прямо сегодня.
