Привет, Хабр! В 2020 году компания решила вывести на рынок линейку продуктов Platform V. Для них нужна была документация, которая на тот момент велась в Confluence. Нам предстояло проделать сложную и дорогую работу: собрать документы на нужные версии, привести тексты к единому стилю и терминологии, оформить как комплект документации от поставщика ПО. Расскажу, какие инструменты мы в СберТехе использовали, почему перешли от документирования в Confluence нa Docs-as-a-Code и создали инструмент Platform V GetDocs, который помогает эффективно писать документацию.
Почему wiki-системы — не лучший выбор для продуктовой документации
Wiki-системы — отличное решение для баз знаний, энциклопедий, проектной и рабочей документации. Но у продуктовой документации свои особенности и задачи, для которых wiki-системы не очень подходят.
Под продуктовой документацией я подразумеваю документы, которые клиент получает вместе с продуктом, и которые нужны для успешного развертывания, конфигурирования и эксплуатации. Из этого вытекают технические требования:
Версионирование документации вместе с продуктом. Это особенно важно, если поставщик поддерживает несколько версий продукта и, соответственно, документаций к ним.
Хорошая управляемость архитектурой контента: переиспользование текстов, подстановочные значения, формирование разных наборов документов из одних исходных текстов.
Генерация документации на API, базы данных, формирование документов из структурированных данных, полученных из внешних систем.
Различные выходные форматы: брендированный сайт для клиентов, печатные формы, документация в дистрибутиве.
Локализация.
Некоторые из этих требований можно реализовать и с помощью wiki-системы. Но решение получается дорогим как в разработке, так и в обслуживании. Основные недостатки wiki-системы для работы с продуктовой документацией:
Сложное версионирование.
Тяжеловесность и неповоротливость при больших объёмах.
Потеря контента при частых изменениях в объёмных текстах.
Невозможность генерирования документации на API, сложность или невозможность работы со структурированными данными.
Сложность настройки выходных форм. Как правило, для них делают отдельное решение.
Преимущества подхода Docs-as-a-Code
Для продуктов с регулярным релизным циклом, одновременной поддержкой нескольких версий и документацией в разных форматах и комплектности (для внутреннего использования, клиентов или заказчиков, регулирующих институтов) оптимальное решение — подход Docs-as-a-Code. Суть концепции в том, что работа с документацией ведется по тем же принципам, что и разработка кода:
Хранение и версионирование документации в системе контроля версий, как правило, вместе с кодом продукта.
Простая интеграция обновления документации с системами ведения задач.
Использование логической разметки тестов, облегчённых языков разметки, понятных широкому кругу технических специалистов: разработчикам, тестировщикам, аналитикам, техническим писателям, менеджерам.
Совместная разработка документации, рецензирование и согласование документации по правилам проверки кода.
Разработка правил оформления документации отдельно от контента.
Организация автоматического тестирования, сборки и публикации документации в рамках типовых DevOps‑процессов.
Подход Docs-as-a-Code обеспечивает надёжную и прозрачную работу с контентом и не требует отдельных трудоёмких операций по оформлению контента при его разработке.
Особенности составления документации на Platform V
В СберТехе практически сразу решили перейти с Confluence на Docs-as-a-Code. И, как и многие компании, мы встали перед выбором инструмента, который бы позволял легко работать с документацией. В наших условиях было выгодно сделать свой продукт:
Объёмная продуктовая линейка: более 80 программных продуктов из более 200 чем программных компонентов.
Большая производственная команда: более 2000 сотрудников.
Стандарт документации и внутренние стандарты, регламентирующие разработку продуктов.
Необходимость формирования документации на различные виды API.
Частые изменения требований к составу документации и её поставке.
Platform V GetDocs — продукт для производства документации в парадигме Docs-as-a-Code
Platform V GetDocs — простой и удобный инструмент для разработки документации Docs-as-a-Code и сайта документации. Поддерживает все необходимые сценарии, легко расширяется и отвечает потребностям команд разработки и техписателей.
Основные функциональные особенности и преимущества:
Простая и гибкая разметка текстов: MyST Markdown, reStructured Text. Поддержка подстановочных значений, переиспользования текстов, включения и исключения текстов по признакам сборки.
Поддержка работы с разными конфигурациями репозиториев:
Монорепозиторий документации: информации о всех продуктах в выделенном репозитории.
Отдельный репозиторий для документации на каждый продукт.
Единый репозиторий для кода продукта и документации.
Сборка документации:
Различные выходные форматы документации: статический сайт в архиве для дистрибутива, печатные формы PDF, DOCX, веб‑версия для сайта документации.
Сборка комплектов документации специального назначения, например, для регистрации в Едином реестре российского ПО и др.
Сборка справочников API из исходных кодов и спецификаций: OpenAPI, AsyncAPI, GraphQL, Java API, gRPC, JSON‑RPC.
Отображение структурированных данных в виде отдельных документов или в рамках одного документа (источники JSON, XML, YAML и др.).
Простое управление сборкой через интерфейс и возможность сборки как отдельных комплектов документации, так и сайта целиком.
Высокая скорость сборки: меньше 1 минуты для одного комплекта документации в режиме разработки, около 5 минут для публикации документации на сайте для читателей.
Проверка документации:
Отчёт с переходом в один клик к источнику ошибки в репозитории.
Настраиваемые и легко пополняемые правила из внутренних руководств и брендбуков компании.
Проверка справочников API.
Проверка целостности ссылок и конфигурации сайта.
Проверка структуры документов и разделов.
Проверка текстов на иллюстрациях, синтаксиса логической разметки, грамматики русского языка.
Поиск и сверка именованных сущностей.
Согласование и публикация:
Разделение по уровням готовности к публикации: документация в разработке, согласована и готова к публикации, опубликована на сайте.
Контроль публикации на сайте готовой документации.
Синхронизация контента между разными инсталляциями (внутренний сайт и внешние сайты для клиентов).
Отображение документации:
Единый стиль отображения для всего контента для разных источников исходных файлов: документы в MD/RST, справочники API, структурированные данные.
Два режима отображения на сайте: для разработчика документации (расширен дополнительными инструментами, например переход к исходнику документации, переход к отчету о валидации) и для читателя.
Техническая реализация Platform V GetDocs
Продукт реализован в виде микросервисов, запакованных в Docker-контейнеры. Их можно за считанные секунды развернуть на любой машине с любой операционной системой, где установлен Docker. В качестве движка генерирования документов используется Sphinx с подключённым парсером MyST Markdown. Проверка выполняется целым набором средств: Vale, mdlint, OCR, своими решениями.
Мы также добавили в продукт конфигурацию для разворачивания в кластере Kubernetes. Использование Platform V GetDocs в Kubernetes с его богатой экосистемой даёт весомые преимущества при администрировании, поддержке и расширении продукта. Например, мы не стали изобретать интерфейс сборки документации, а просто развернули Argo Workflows и настроили там нужные конвейеры в формате YAML.
Из коробки получили интеграцию с корпоративной системой аутентификации и системой контроля версий, визуальную историю и прогресс сборок, удобные логи на каждом этапе сборки и список получаемых артефактов.
Чтобы все комплекты документации были в едином стиле и проверялись по единым правилам, мы вынесли в отдельные репозитории шаблоны сайта и печатных форм, правила проверки и конфигурирование основных сайтов.
Platform V GetDocs включает в себя два контура: сборка документации и сайт документации. В упрощённом виде архитектура продукта представлена на схеме.
Основные преимущества технической реализации:
Docker‑образы обеспечивают единую и защищённую среду функционирования компонентов в любом окружении.
Микросервисная архитектура позволяет расширять и выборочно обновлять продукт без полной пересборки и разворачивания всего решения.
Функционирование в кластере Kubernetes даёт высокую скорость, доступность, автоматическую отказоустойчивость и масштабируемость решения, что особенно важно при огромных объёмах постоянно обновляющейся документации. Дополнительно мы можем автоматически обновлять и разворачивать новые компоненты в считанные секунды, и в случае ошибок в разработке быстро откатываться на стабильные версии. И всё это без каких‑либо простоев!
Связка Sphinx и MyST Parser даёт средства для гибкого ведения документации: богатую семантическую разметку, легкое расширение разметки, смешанное использование MD/RST, сложные таблицы, включение/исключение контента по признакам, подстановочные значения, единый источник, локализацию, конфигурируемые шаблоны для разных форматов генерируемой документации. Дополнительно заменили conf.py на более простой YAML.
Гибкая настройка шаблона сайта документации.
В следующих статьях расскажем о реализации нашего продукта, поделимся рецептами организации документирования для технически сложных программных продуктов и покажем, как Platform V GetDocs упрощает рабочий процесс.
Светлана Каюшина
Руководитель документирования Platform V
