Привет, Хабр! В 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