Представьте, что вы разработали программное обеспечение. Все идеально: код отточен, тесты пройдены, система готова к работе. Но тут встает вопрос: как отправить документацию заказчику?

Всем привет! Меня зовут Катя, я развиваю Gramax, open source-платформу для управления технической документацией. В этой статье хочу поделиться впечатлением от стандартных способов передачи документации на заказную разработку. А также рассказать о том, как этот процесс можно автоматизировать с помощью Gramax.

Можем написать PDF или DOCX

Классический путь — отправить PDF или DOCX. Но это неудобно: такие файлы сложно поддерживать в актуальном состоянии, их трудно искать, а управление версиями превращается в хаос. В конечном итоге заказчик получает папку с десятками однотипных документов, где невозможно понять, что действительно актуально.

• Сложности обновления. Каждое изменение в ПО требует правок в файлах, что приводит к десяткам версий вроде doc_v1.3_final.pdf. Отследить актуальную — задача не из легких.

• Человеческий фактор. Ручное форматирование и экспорт увеличивают риск ошибок: устаревшие данные, битые ссылки, несогласованные версии.

Или дать доступ к внутренней wiki?

Другой вариант — дать доступ в вашу внутреннюю wiki-систему. Но это требует создания пользователей, покупки лицензий и настройки доступа. Кроме того, не все заказчики готовы хранить документацию у вендора или интегратора.

• Сложная настройка. Нужно создавать учетные записи, настраивать права доступа и обучать заказчика работе с системой.

• Лицензии. Платформы вроде Confluence требуют затрат на лицензии, которые ложатся на заказчика или вендора.

• Зависимость от вендора. Хранение документации на серверах разработчика не всегда приемлемо, особенно для чувствительных данных.

Эти подходы не масштабируются, тормозят процессы и раздражают всех участников проекта.

Как можно сделать иначе

В Gramax мы используем подход Docs as Code: документация пишется в Markdown, хранится в Git, а пользователи работают с ней через удобный и привычный визуальный редактор. Gramax помогает командам оптимизировать процесс подготовки и отгрузки документации, а также поддерживать единый источник правды. И конечно, мы не могли обойти стороной процесс передачи документации заказчику.

Какие предлагаем варианты:

• Передавать статический сайт с документацией. Подойдет тем, кто хочет сделать работу сотрудников заказчика реально удобной: им не придется искать ответы на свои вопросы в длинных файлах, достаточно зайти на сайт и ввести запрос в поисковую строку. Это безопасно: сайт разворачивается в контуре заказчика и легко обновляется с каждой поставкой новой версии продукта.

• Встроить формирование PDF или DOCX в CI/CD сборки продукта. Этот вариант будет удобен в случае, если заказчик не готов тратить время на настройку сайта или по требованиям проекта должен быть PDF или DOCX. Документация сформируется автоматически из Markdown-файлов в репозитории и попадет в дистрибутив с продуктом.

Оба способа доступны, если технические писатели работают в подходе Docs as Code.

Готовим документацию

Ключевая идея Gramax — документация должна быть частью инженерной экосистемы, а не отдельным процессом, который отнимает время. Мы целимся в Everything as Code, где код, документация, архитектурные решения и знания управляются единообразно, с использованием лучших инженерных практик. Подробнее об этом рассказывали в статье.

Потому сама подготовка документации выглядит следующим образом:

1. Технический писатель открывает приложение Gramax, подключает корпоративное Git-хранилище и загружает репозиторий с продуктом.

   

2. Писатель редактирует статьи и создает новые. Согласует их с коллегами и руководителем проекта с помощью встроенного механизма Merge Request.

   

3. Публикует свои изменения в репозиторий продукта. Каждая статья — обычный Markdown-файл. Таким образом разработчики просматривают документацию в привычной IDE, а писатели, менеджеры и аналитики — в удобном приложении.

Передаем статический сайт

Документация компилируется в статические HTML-файлы в рамках CI/CD-процесса. Для этого используется Gramax CLI, который позволяет быстро собрать портал документации без дополнительной разработки.

• Что передаем: HTML, CSS и JSON-файлы.

• Как получаем: на стороне разработчика в CI/CD с помощью Gramax CLI.

• Где разворачивается: на стороне заказчика, в любом веб-сервере (например, nginx).

Пример настройки CI/CD в Gramax CLI:

stages:
  - build

variables:
  BUILD_DIR: build

build:
  stage: build
  tags:
    - docker-linux-amd64
  image: node:latest
  script:
    - npx gramax-cli build -d $BUILD_DIR
  artifacts:
    paths:
      - $BUILD_DIR

В результате выполнения получаем файлы с сайтом документации, их можно приложить в сборку продукта.

После получения дистрибутива с продуктом и сайтом заказчику достаточно распаковать файлы и разместить их на сервере. Сотрудники смогут просматривать документацию на удобном сайте с поиском и навигацией.

Настраиваем генерацию PDF или DOCX в CI/CD

Если документация лежит в одном репозитории с кодом, можно сформировать PDF или DOCX-файл с инструкциями в процессе сборки самого продукта. Для этого также используется Gramax CLI.

• Что передаем: PDF или DOCX, сгенерированный автоматически.

• Как получаем: на стороне разработчика в CI/CD с помощью Gramax CLI.

В корне репозитория создайте файл .gitlab-ci.yml, если его нет, или дополните его добавив еще один этап:

stages:
  - export

variables:
  EXPORT_FILE_PATH: artifacts/export

export:
  stage: export
  tags:
    - docker-linux-amd64
  image: node:latest
  script:
    - npx gramax-cli export -f pdf -o $EXPORT_FILE_PATH -y

  artifacts:
    paths:
      - artifacts

В результате выполнения получаем файл с документацией, его можно приложить в сборку продукта.

Что получаем в итоге

• Единый источник правды. Документация хранится в Git рядом с кодом. Все изменения проходят через ревью, что исключает несогласованность. Разработчики и техписы работают в одной экосистеме.

• Только актуальная документация. CI/CD гарантирует, что PDF или сайт генерируются на актуальную версию продукта. Заказчик не получает устаревшие файлы или конфликтующие версии.

• Быстрая отгрузка. Статический сайт собирается за секунды (100 страниц — менее 5 секунд с Gramax CLI). PDF генерируется в рамках сборки продукта, не требуя дополнительных действий. Заказчик получает готовый артефакт: архив с сайтом или PDF.

• Безопасность. Статический сайт не требует серверного приложения и дополнительных компонентов, быстро работает, а также полностью безопасен из-за своей статичной структуры. Документация разворачивается в контуре заказчика, исключая зависимость от серверов вендора. Чувствительные данные остаются под контролем заказчика.

Итог

Передача документации — это часть поставки продукта. Gramax позволяет встроить ее в цепочку отгрузки: прозрачно, безопасно и без боли. Такой подход снимает вопросы «а где актуальная версия?», «а почему в PDF не то?» и «а что мне теперь с этим делать?».

Открыто, бесплатно, и с сообществом

• Смотрите наш сайт — https://gram.ax

• Проверяйте исходники в GitHub и GitVerse.

• Вступайте в комьюнити — https://t.me/gramax_chat