![43305caedb518de96270812b0f1aa5c5.jpg](/_next/image?url=%2Fapi%2Fmedia%3Fid%3D43305caedb518de96270812b0f1aa5c5_3283d4bc30.jpg&w=1536&q=75)
Привет! В 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 и сайта документации. Поддерживает все необходимые сценарии, легко расширяется и отвечает потребностям команд разработки и техписателей.
![a0fed211ed6dee25dee1651c86a92188.png](/_next/image?url=%2Fapi%2Fmedia%3Fid%3Da0fed211ed6dee25dee1651c86a92188_bd4da8b85c.png&w=1536&q=75)
Основные функциональные особенности и преимущества:
1) Простая и гибкая разметка текстов: MyST Markdown, reStructured Text. Поддержка подстановочных значений, переиспользования текстов, включения и исключения текстов по признакам сборки.
2) Поддержка работы с разными конфигурациями репозиториев:
- Монорепозиторий документации: информации о всех продуктах в выделенном репозитории.
- Отдельный репозиторий для документации на каждый продукт.
- Единый репозиторий для кода продукта и документации.
3) Сборка документации:
- Различные выходные форматы документации: статический сайт в архиве для дистрибутива, печатные формы PDF, DOCX, веб‑версия для сайта документации.
- Сборка комплектов документации специального назначения, например, для регистрации в Едином реестре российского ПО и др.
- Сборка справочников API из исходных кодов и спецификаций: OpenAPI, AsyncAPI, GraphQL, Java API, gRPC, JSON‑RPC.
- Отображение структурированных данных в виде отдельных документов или в рамках одного документа (источники JSON, XML, YAML и др.).
- Простое управление сборкой через интерфейс и возможность сборки как отдельных комплектов документации, так и сайта целиком.
- Высокая скорость сборки: меньше 1 минуты для одного комплекта документации в режиме разработки, около 5 минут для публикации документации на сайте для читателей.
4) Проверка документации:
- Отчёт с переходом в один клик к источнику ошибки в репозитории.
- Настраиваемые и легко пополняемые правила из внутренних руководств и брендбуков компании.
- Проверка справочников API.
- Проверка целостности ссылок и конфигурации сайта.
- Проверка структуры документов и разделов.
- Проверка текстов на иллюстрациях, синтаксиса логической разметки, грамматики русского языка.
- Поиск и сверка именованных сущностей.
5) Согласование и публикация:
- Разделение по уровням готовности к публикации: документация в разработке, согласована и готова к публикации, опубликована на сайте.
- Контроль публикации на сайте готовой документации.
- Синхронизация контента между разными инсталляциями (внутренний сайт и внешние сайты для клиентов).
6) Отображение документации:
- Единый стиль отображения для всего контента для разных источников исходных файлов: документы в 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 включает в себя два контура: сборка документации и сайт документации. В упрощённом виде архитектура продукта представлена на схеме.
![c7008d5b449f78b676e5dfc07169968b.png](/_next/image?url=%2Fapi%2Fmedia%3Fid%3Dc7008d5b449f78b676e5dfc07169968b_a8f250f937.png&w=1536&q=75)
Основные преимущества технической реализации:
- Docker‑образы обеспечивают единую и защищённую среду функционирования компонентов в любом окружении.
- Микросервисная архитектура позволяет расширять и выборочно обновлять продукт без полной пересборки и разворачивания всего решения.
- Функционирование в кластере Kubernetes даёт высокую скорость, доступность, автоматическую отказоустойчивость и масштабируемость решения, что особенно важно при огромных объёмах постоянно обновляющейся документации. Дополнительно мы можем автоматически обновлять и разворачивать новые компоненты в считанные секунды, и в случае ошибок в разработке быстро откатываться на стабильные версии. И всё это без каких‑либо простоев!
- Связка Sphinx и MyST Parser даёт средства для гибкого ведения документации: богатую семантическую разметку, легкое расширение разметки, смешанное использование MD/RST, сложные таблицы, включение/исключение контента по признакам, подстановочные значения, единый источник, локализацию, конфигурируемые шаблоны для разных форматов генерируемой документации. Дополнительно заменили conf.py на более простой YAML.
- Гибкая настройка шаблона сайта документации.
В следующих статьях расскажем о реализации нашего продукта, поделимся рецептами организации документирования для технически сложных программных продуктов и покажем, как Platform V GetDocs упрощает рабочий процесс.