Перейти к основному содержимому

Обновление документации

· 3 мин. чтения
Антон Трофимов
Менеджер проекта

На днях состоялось обновление документации для продукта KOMRAD. Спешим раскрыть все секреты касательно того, как это произошло.

Немного истории

3 года назад мы готовили сертификационную документацию по требованию ФСТЭК и задумались над тем, что сложно поддерживать её в актуальном состоянии. Дело в том что сертификационная документация очень долго обновляется и вообще это сложный процесс для всех:

  • для заказчика (он постоянно должен у спрашивать саппорта "а может ли продукт то, что не описано в руководстве, и как это сделать?"
  • для разработчика (согласовать новую версию руководства с ФСТЭК, а у нас оно лежит на диске, пересчитать КС и отправить всем)
  • для ФСТЭКа ничего кроме руководства не меняется, но документация все равно проходит все формальные процессы в ведомстве, и это может быть очень долго
  • для саппорта (у саппорта должна быть либо своя база знаний, либо мини-инструкции на любой случай)

Antora

Поэтому мы задумались о том, чтобы иметь электронную документацию, которая потенциально решила бы все наши проблемы. В первый раз мы не выбирали долго, форкнули готовый проект на Antora и переделали её под себя настроили CI/CD, начали документировать. Антора немного специфична, например, формат разметки текста в ней asciidoc. Поскольку это была наша первая электронная документация, мы хотели быстро её сделать и быстро выложить. С первым мы справились действительно быстро, сделали простое деление на руководство администратора и оператора, остальные статьи были отсылками к другим документам, но, в итоге, мы посчитали, что более структурировано будет выглядеть архитектура с продуктовой логикой, вдохновлялись документацией.

Стоит отметить, что у таких проектов, как Антора есть своя философия, там есть своя структура папок, есть рекомендации по CI, но мы, в большей степени, её игнорировали с самого начала. И не стоит забывать, что мы переделывали форк под себя, мы пытались оградить UI и бэкенд специалистов от работы, связанной с документацией, но повышать зависимости надо и документация начала ломаться. Большой проблемой стал поиск, когда локальный поиск сломался, мы попробовали его переписать, но безуспешно, UI жаловался на легаси код и отклонял наши хотелки, например, возможность зумить изображения. Вершиной всего стало то, что из-за неверной настройки нам пришлось бы потратить много времени на добавление новых версий, хотя, в репозитории документации уже были готовые ветки, из которых просто нужно было собрать версии.

Муки выбора

Есть достаточное количество проектов для электронной документации. В большей степени, они используют Markdown, очевидно, он проще и популярнее, поэтому для нас это было не ограничением, но препятствием. Мы рассматривали такие проекты:

По набору функций нас впечатлили Docusaurus и Gitbook, но у Docusaurus больше запас на развитие документации, поэтому мы сделали выбор в его пользу. Развитие - это фичи, которые можно опционально подключить, в docusaurus - это плагины, сейчас их не так много, по причине обновления docusaurus до версии 3, на 2-й версии их было огромное количество, но не все ещё добавили поддержку 3-й версии.

Docusaurus

Новые фичи:

  • локальный поиск
  • зум изображений
  • работа с формами
  • тёмная тема
  • версионирование
  • новое индексирование

Мы перенесли все документы в их исходном виде и добавили ещё одну версию 4.5.Х, сейчас она в стадии Beta и выдаётся по запросу, но уже сейчас есть доступ к её актуальной документации. Новые функции и новая логика элементов и страниц будет правиться только для версии 4.5.