Представьте, что вы разработали программное обеспечение. Все идеально: код отточен, тесты пройдены, система готова к работе. Но тут встает вопрос: как отправить документацию заказчику?
Всем привет! Меня зовут Катя, я развиваю 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, где код, документация, архитектурные решения и знания управляются единообразно, с использованием лучших инженерных практик. Подробнее об этом рассказывали в статье.
Потому сама подготовка документации выглядит следующим образом:
Технический писатель открывает приложение Gramax, подключает корпоративное Git-хранилище и загружает репозиторий с продуктом.
Писатель редактирует статьи и создает новые. Согласует их с коллегами и руководителем проекта с помощью встроенного механизма Merge Request.
Публикует свои изменения в репозиторий продукта. Каждая статья — обычный Markdown-файл. Таким образом разработчики просматривают документацию в привычной IDE, а писатели, менеджеры и аналитики — в удобном приложении.
Передаем статический сайт
Документация компилируется в статические HTML-файлы в рамках CI/CD-процесса. Для этого используется Gramax CLI, который позволяет быстро собрать портал документации без дополнительной разработки.
Что передаем: HTML, CSS и JS-файлы.
Как получаем: на стороне разработчика в 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
Вступайте в комьюнити — https://t.me/gramax_chat
