Представьте, что вы разработали программное обеспечение. Все идеально: код отточен, тесты пройдены, система готова к работе. Но тут встает вопрос: как отправить документацию заказчику?
Всем привет! Меня зовут Катя, я развиваю 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
Комментарии (8)
winorun
20.06.2025 16:21Я пишу документацию для себя, пробовал разное. Начинал с маркдауна. Его просто не хватает на что либо. После мардауна был асидок. Это было намного лучше, но потом познакомился с typst. И этот вариант зашел на ура. Встроенный парсер json, csv позволяет хранить файлы на основании чего генерировать текст. Возможно создавать свои функции. Нужен например note, создал. Надо изменить, изменил функцию. Довольно простая документация и многое другое
funca
20.06.2025 16:21Для личных заметок есть obsidian.md/. Это редактор, где маркдаун довели до
абсурдаабсолюта. Там из маркдауна через платины можно ходить хоть в базу, хоть в API, хоть в AI.winorun
20.06.2025 16:21Как вы верно указали обсидиан это для личных заметок, я же говорю о рабочей документации. В случае моего отсутствия коллеги открыть пдф файл сумеют, при чем на своем устройстве. Да и городить огород с кучей директорий обсидиана как то не хочется.
FabrLik
Благодарю за статью, прочитал с интересом подход.
В силу своей должности с документацией работаю постоянно.
Озвученная вами боль известна очень хорошо :)
Маркдаун имеет свои преимущества, однако, большая часть коммерческого ПО имеет визуальный интерфейс в том или ином роде, который в вашей статье не подсвечивается.
Как итог:
1) Как вы будете хранить информацию о дизайне в маркдауне?
Есть же страницы с динамическим наполнением, а не только статичная HTML.
По сути вам придется делать ровно тот же хаос, который существует в папке любого проектного менеджера.
Версия 1, версия 2, версия 122.
Кстати, из практики, нумерацию в таких случаях проще вести не в версиях, а в датах обновления.
"20250620_Главная страничка"
Тогда внутри папки файлы всегда ложатся в хронологическом порядке и легко фильтруются.
final и прочие надписи - путь в пучину легаси без документации :)
2) ТЗ коммерческого сектора в том или ином виде предполагает наличие User Flow, которое предполагает наличие картинок/референсов/макетов, которые предполагают, что они где-то как минимум должны быть постоянно залинкованы.
Разработчик ушел, сервер потушен - ваша документация умерла, потому что отвалились все картинки.
Аналогично фигма.
Как итог - картинки должны быть доступны локально в 100% случаев.
Т.е. сам файл документации должен хранить внутри себя все картинки и их расположение без деплоя кода на сервер.
По итогу предложенный вами вариант - очень интересная тема для менеджеров из IT (бывшие тимлиды и разрабы, например), которым привычен маркдаун.
И вообще не работает для простых менеджеров (обычный руководитель среднестатистический после курсов "IT за 2 часа", коих, наверное, большинство сейчас).
Попробуйте подумать и в сторону UI-документации для полного охвата любого проекта и будет нам всем счастье :)
Из моей практики лучшим сочетанием пока является:
1) Маркдаун для технической документации
2) pptx для всей остальной
Если вам известно что-то более интересное, то буду рад взаимовыгодному диалогу :)
Sap_ru
А ресурсы в pptx ручками по одному обновлять? Так а чем тогда какой-нибудь odt формат от OpenOffice Wrirter не подходит? Та же фигня, но с возможностью автоматизации (через боль, но все же) и экспорта во что угодно. От HTML и PDF до богомерзкого .doc.
Я именно там подобную документацию делал. Из плюсов - иерархия стилей и нумерации, которая позволяет сохранять однообразие представления и быстро править структуру документа (когда у вас в разделе из ста пунктов новый пункт добавился и при этом ещё и нумерация разделов изменилась).
В нем реально можно зафигачить документацию из четырёх связанных документов на 250 страниц с картинками и таблицами, а потом поддерживать её в актуальном состоянии на протяжении нескольких лет, по мере эволюции продукта. Хотел бы я посмотреть, как вы это в своём pptx исполните.
FabrLik
OpenOffice не использовал, подсказать не смогу :)
Но посмотрю, что имеете ввиду.
По ресурсам да - ручками, как и в маркдауне придется правки вносить.
Тут вариантов не шибко много :)
Если под автоматизацией понимается пуш в гит, так pptx тоже можно класть, как и любой файл - ничем не отличается и ровно таким же образом процесс CI-CD настраивается.
Другой момент, что одновременно править нельзя будет файл, так как смеджить содержание pptx не выйдет.
Из преимуществ pptx имеет возможность вставить картинку "как элемент" и настроить его расположение.
Т.е. не линк на картинку, а именно изображение внутри.
Аналогично с файлами можно поступать.
А при необходимости их оттуда можно забрать в исходном виде.
В частности макетирование сайта можно сделать с кнопками-переходами (ссылка на страницу документа).
По итогу получаем UI кликабельный в режиме демонстрации, который можно тыкать самому, а может тыкать заказчик.
Из практики очень хорошо заходит у заказчика на первых этапах проектирования структуры, так как за 1 день заказчик получает возможность визуализировать то, что он хотел.
Получаем макет на минималках, в котором без участия разработчиков может даже сам заказчик переместить объекты так, как ему нравится.
Иногда в процессе оказывается, что не хватает кнопок перехода и т.п.
Быстро, дешево, удобно.
Даже примитивную анимацию можно делать а-ля смена цвета кнопок, если время позволяет :)
.doc, на мой взгляд, только для юридических документов можно использовать, потому что по итогу в режиме редактирования там юристы и переписываются дополняя друг-друга, стандартная форма их коммуникации.
В маркдауне они писать принципиально не будут.
И опять же, финальный файл спокойно вкладывается в pptx именно в виде файла (не линком).
Для ведения документации пробовал - выходит мрак :)
Я к тому, что файл pptx выступает как своеобразный локальный архив, внутри которого лежат без линков все нужные версии файлов, которые по тем или иным причинам нельзя положить в маркдаун :)
а) Независимость от вендора
б) Независимость от сервера
в) Дублирование у разработчика и заказчика гарантирует сохранность
Как писал выше:
1) Маркдаун основа
2) pptx для всего, что имеет визуал + что не влезло в маркдаун.
Изображения, макеты, схемы нестандартные и т.п.
Но опять же, если какие-то иные инструменты есть - только за.
Проект без документации при длительной поддержке - это боль :)
krakenkaken Автор
Спасибо за ваши комментарии! Я не очень поняла, какие сложности могут возникнуть с картинками, постараюсь опираться на тезис "сам файл документации должен хранить внутри себя все картинки и их расположение без деплоя кода на сервер". Сейчас расскажу, как это устроено.
В Gramax вы можете добавлять в статьи:
- Диаграммы.
- Любые картинки.
- Видео.
Диаграммы и картинки
Сам файл диаграммы или картинки сохраняется в репозитории в исходном виде. В Markdown-файле статьи сохраняется путь до ресурса (диаграммы или картинки) в репозитории.
Это позволяет нам работать локально: при загрузке всего репозитория у редактора корректно отображается как статья, так и все ее ресурсы.
Так как ресурсы хранятся в самом репозитории, ситуация "Разработчик ушел, сервер потушен - ваша документация умерла, потому что отвалились все картинки" невозможна.
Видео
Так как хранить в репозитории большие файлы (а видео обычно большие) не очень хорошая практика, мы позволяем в редакторе добавить ссылку на видео из любого источника с возможностью стриминга. Это может быть YouTube, RuTube, DropBox и так далее. Видео как раз является этим динамическим элементом, о которых вы писали. Понятное дело, что в PDF оно не воспроизведется, но ссылка сохранится и по ней можно будет перейти.
Информация о дизайне
В статье мы описываем документацию, которая передается после завершения проекта. Это, как правило, руководство пользователя, администратора, техническая спецификация. На этом моменте нет потребности согласовывать дизайн. Описать юзерфлоу — да, нужно. Но это делается в стандартной форме инструкции или туториала, где фокус не на элементах интерфейса, а на действиях пользователя.
Нумерация версий
Версии документации, в идеале, должны соответствовать версиям продукта. Каждая версия хранится в отдельной ветке. Например, из ветки
v1.1.0мы создадим веткуv1.1.1и добавим в нее новые фичи + описание этих фич.Ограничения Markdown
Да, обычный Markdown довольно скуп на оформление. Поэтому мы самостоятельно его расширили: добавили сложные таблицы, яркие заметки, вкладки и другие необходимые элементы. Так как даже с нашими расширениями он может подойти не всем, постепенно расширяем и поддерживаемые языки разметки: например, недавно добавили MDX (Markdown + XML) и GitHub Flavored Markdown (для тех, кто оформляет README в GitHub). Постепенно будет добавлять и другие языки.
Надеюсь, правильно поняла вопросы и понятно на них ответила. Ну и не могу упустить возможность написать, что полезных и приятных возможностей у нас много. О них подробнее можно узнать в документации:
https://gram.ax/resources/docs