Привет, Хабр! Меня зовут Катя, я лидирую Gramax, open-source платформу для управления технической документацией. Однажды мы с коллегами утонули в хаосе рабочих документов: без версий, без согласований, без истории принятых решений. Это подтолкнуло нас к созданию Gramax — инструмента, который интегрирует документацию в процесс разработки, делая его прозрачным и управляемым.

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

Кто, что, когда и зачем меняет

Что было у нас и часто бывает у других: кто-то переписывает требования или инструкцию, и никто толком не понимает, что именно изменилось. Почему поменяли? Что было раньше? Кто согласовал? — найти ответы почти невозможно.

• Нет понимания, что изменилось. Документ выглядит так же, но внутри могут быть полностью другие требования или описания. Приходится сравнивать версии вручную (если они вообще сохранились).

• Неясно, зачем внесли правки. Кто решил переписать требования? Почему убрали тот пункт? Что стало основанием для изменения? Контекст правок теряется в чатах и звонках, а спустя неделю об этом никто уже не помнит.

• Не видно, кто согласовал. Участники команды не понимают, была ли правка согласована или кто-то просто внес ее по своей инициативе. Не отследить, какие документы готовы, а какие в процессе.

Нам было важно видеть, кто что предложил, как это обсуждали и к какому варианту пришли в итоге. Без гаданий, без лишних вопросов.

Давайте сначала: что такое Gramax

• Визуальный редактор для Markdown с поддержкой OpenAPI, Mermaid, PlantUML и Draw.io.

• Интеграция с популярными Git-хранилищами, встроенный Git-клиент, запросы на слияние, версионирование.

• Независимость от вендоров. Потому что Gramax это self-hosted решение с открытым исходным кодом.

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

Gramax помогает командам хранить всю документацию рядом с кодом, автоматизировать процессы и поддерживать единый источник правды.

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

Теперь о процессах: как использовать

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

Системные и бизнес-аналитики: формирование требований

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

1. Аналитик открывает Gramax, выбирает шаблон для формирования требований. Описывает все в визуальном редакторе с Mermaid-диаграммами для иллюстрации бизнес-процесса.

2. Документ сохраняется в ветке spec-payment-module в Git-репозитории. Аналитик создает запрос на слияние в master, назначая архитектора и менеджера на ревью.

3. В интерфейсе Gramax команда обсуждает документ с помощью комментариев. Аналитик вносит правку исправления за минуты, обновляя ветку.

4. После согласования документ сливается в master.

Результат: постановка оформлена по шаблону, история изменений сохранена в Git.

Архитекторы: проектирование и ADR

Задача: архитектор должен создать архитектурное решение (ADR) для платежного модуля, согласовать его и сохранить рядом с кодом.

1. Архитектор создает ADR в Gramax: описывает архитектуру платежного модуля, добавляет и редактирует C4-диаграммы прямо в интерфейсе статьи. Файл сохраняется в ветке feature/adr-payment-module.

2. Архитектор создает запрос на слияние в master, приглашая менеджера, аналитиков и разработчиков на ревью.

3. Аналитики и разработчики просматривают изменения на диаграмме: сравнивают в виде изображения или в виде кода.

4. После обработки комментариев и правок ADR сливается, становясь частью репозитория.

Результат: ADR доступны рядом с кодом, история решений сохранена, а согласование занимает меньше времени благодаря подробному диффу в Gramax.

Технические писатели: подготовка пользовательской документации

Задача: технический писатель должен подготовить гайд по использованию платежного модуля и API-документацию, опубликовать их на портале.

1. Писатель создает инструкции по использованию, кодовые блоки (например, curl для API-запросов) и OpenAPI-спецификацию через встроенный сервис. Файлы публикуются в репозиторий в ветке feature/docs-payment-module.

2. Писатель запускает автоматические проверки на соответствие корпоративному стайлгайду и глоссарию.

3. Менеджер продукта просматривает все изменения по задаче: не отдельные документы, а список всех правок с удобной подсветкой. Затем оставляет комментарии или подтверждает готовность для публикации в master.

4. DevOps разворачивают портал документации с помощью Docker или Gramax CLI. Портал обновляется автоматически каждый раз, когда писатель вносит изменения в master.

Результат: пользователи читают документацию на удобном портале с интеллектуальным поиском, чат-ботом на базе ИИ, подсветкой кода и брендированным дизайном. Они могут переключаться разные языки и версии документации — например, если продукт поставляется в разные страны и клиенты используют разные версии продукта.

DevOps-инженеры: автоматизация поставки документации

Если вы разрабатываете ПО для заказчиков, вместе с автоматической сборкой ПО можно наладить автоматическую сборку PDF, DOCX или HTML-файлов с документацией.

1. DevOps встраивает в пайплайн сборки ПО автоматическую генерацию файла с документацией с помощью Gramax CLI.

2. При сборке релиза пакет (ПО + документация) автоматически передается Delivery-менеджеру для поставки заказчику.

Результат: каждая поставка включает актуальную документацию, сгенерированную без ручного труда, что ускоряет релиз.

И еще о Gramax

• Лаконичный интерфейс. Как в приложении, так и на портале документации. Страдать не придется.

• Абсолютная независимость от нас (разработчиков Gramax). Браузерное и десктопное приложение работают на клиенте, информация хранится в вашем Git-хранилище, портал документации разворачивается на вашем сервере.

• Регулярные обновления. Да, мы стартап. Да, мы отгружаем много фич каждую версию.

Фичи для практического применения

• Mermaid, Draw.io, PlantUML, Open API. Со встроенным редактором!

• Мультиязычность. Одну документацию можно отобразить на 17 языках.

• Версионирование. Одну документацию можно отобразить для разных версий.

• Развитие ИИ-интеграций. Уже есть свой сервис проверок на соответствие стайлгайду, векторный поиск и чат-бот. Чуть позже появится ИИ-валидация: проверки на дублирование и противоречие информации.

• Экспорт в PDF, DOCX, HTML. Импорт из Confluence и Notion.

• Редактор изображение. Обрезаем, добавляем обводки и нумерацию прямо в статье.

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

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

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

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

Делитесь мнениями в комментариях! Что добавить? Что бесит в текущих инструментах документации? Мы читаем и отвечаем.