Documentation-Driven Development
Есть старая шутка в разработке: «Документация устаревает в момент написания». Большинство команд с этим смирились. Мы пишем код, потом (если успеваем) пишем документацию. Она живет отдельно, обновляется редко, и через полгода становится артефактом прошлого, который никто не читает.
Documentation-Driven Development предлагает перевернуть этот порядок. И дело не только в том, когда писать документацию — дело в том, что она становится центром всего процесса разработки.
Что такое Documentation-Driven Development
DDD — это подход, при котором документация создается до написания кода. Сначала команда описывает, как будет работать система, API, функция или продуктовая фича. Только когда описание согласовано — начинается реализация.
Логика простая: если ты не можешь объяснить, как это должно работать — ты еще не понял, что именно нужно сделать.
Так устроен, например, процесс разработки API в Amazon (подход «Working Backwards»): сначала пишется пресс-релиз и документация для пользователя, и только потом — код. Stripe строит свою документацию как продукт, а не как приложение к продукту. Это не случайно.
Ключевые принципы DDD:
Документ — это контракт. До того как написана первая строчка кода, фронтенд и бэкенд договариваются через документ. Продукт описывает поведение, разработка — интерфейсы. Все договоренности зафиксированы письменно, а не существуют в виде воспоминаний с созвона.
Ранняя валидация. Когда ты пишешь документацию — ты вынужден думать о крайних случаях, об ошибках, об интерфейсах. Проблемы проектирования обнаруживаются на этапе текста, а не дорогостоящего рефакторинга.
Живая документация. Документация обновляется в момент изменения системы — не спустя месяц «когда будет время». Изменил поведение → обновил документ.
Снижение bus factor. Знания не хранятся в голове одного разработчика — они зафиксированы в документах. Когда человек уходит, система остается понятной.
Почему DDD не приживается без правильного инструмента
На практике DDD разбивается о реальность команды: аналитик работает в Confluence, разработчик — в IDE, техпис — еще где-то. У каждого свой инструмент, и документация существует в трех местах одновременно. Кто последний обновил — неизвестно. Какая версия актуальна — непонятно.
В итоге документация есть, но она не работает как инструмент разработки. Она работает как отчетность. Корень проблемы в том, что нет единого места, где вся команда работает с одним и тем же контентом.
Gramax как среда для DDD
Gramax решает эту проблему радикально просто: вся документация хранится в одном Git-репозитории, рядом с кодом. Но каждый участник работает с ней через удобный ему интерфейс.
Аналитик и техпис открывают Gramax-приложение с визуальным WYSIWYG-редактором — никакого markdown, никаких merge-конфликтов вручную. Пишут как в обычном документе.
Разработчик открывает те же файлы в своей IDE — VS Code, JetBrains, любой редактор. Видит markdown, делает правки, коммитит вместе с кодом.
Это не две разные системы с синхронизацией. Это один репозиторий, один файл, два интерфейса к нему. Аналитик сохраняет документ — разработчик видит изменения в своем привычном окружении. Разработчик правит эндпоинт — техпис открывает актуальный черновик в визуальном редакторе.
И когда все готово — документация публикуется для читателей: внутри команды или для клиентов.
Флоу: как DDD выглядит с Gramax
Возьмем конкретный пример — команда добавляет новую функцию в продукт.
Шаг 1. Документ вместо задачи
Процесс начинается не с задачи в таск-трекере, а с документа в Gramax. Аналитик открывает приложение и создает страницу: описывает пользовательский сценарий, ожидаемое поведение, ограничения. Работает в визуальном редакторе — с заголовками, таблицами, блоками предупреждений.
За кулисами Gramax коммитит этот документ в репозиторий. Но аналитик этого не замечает — он просто пишет.
Шаг 2. Ревью документа до кода
Разработчик делает git pull и видит новый файл в /docs/features/. Открывает его прямо в VS Code, читает, правит текст там же — как обычный файл. Если нужно уточнить поведение — правит документ и пушит. Аналитик видит изменения в Gramax.
Это правка одного документа двумя людьми через удобные им инструменты.
Шаг 3. Реализация по контракту
Спецификация согласована. Разработчик реализует функцию — документ служит контрактом. Параллельно в том же PR обновляется техническая документация: разработчик правит ее прямо в IDE рядом с кодом.
Шаг 4. Техпис полирует
Когда функция готова, техпис открывает Gramax и видит актуальный документ — тот же самый, что правил разработчик. Полирует формулировки, добавляет примеры, оформляет для читателя. Все это — в визуальном редакторе, без необходимости разбираться в Git.
Шаг 5. Публикация
Документ публикуется — для команды или для клиентов. Не нужно ничего экспортировать, копировать или переносить в другую систему. Контент уже там, где нужно.
Автоматизации, которые усиливают связку
Так как в Gramax основная идея — создать единый источник правды в репозитории, к документации можно прикручивать стандартные автоматизации. Рассмотрим самые очевидные.
CI-проверка: нет документации — нет мерджа
Самая простая и эффективная автоматизация. В CI-пайплайн добавляется проверка: если PR затрагивает файлы в /src/api/**, то должен быть изменен соответствующий файл в /docs/api/**. Если документация не обновлена — пайплайн падает с понятным сообщением.
# .github/workflows/docs-check.yml - name: Check docs updated with API changes run: | changed_api=$(git diff --name-only origin/main | grep 'src/api/') changed_docs=$(git diff --name-only origin/main | grep 'docs/api/') if [ -n "$changed_api" ] && [ -z "$changed_docs" ]; then echo "API changed but docs not updated. Please update /docs/api/" exit 1 fi
Это превращает «помни обновить документацию» из призыва в технический барьер.
Автогенерация skeleton-документации
При создании нового файла в /src/api/ GitHub Actions автоматически создает черновик документа в /docs/api/ с готовой структурой: описание, параметры, примеры ответов. Разработчику остается заполнить содержимое — структура уже есть.
Это снижает порог входа: не нужно думать «с чего начать», есть шаблон.
Валидация соответствия кода и документации
Для API это можно сделать через OpenAPI: документация генерируется из схемы, а CI проверяет, что схема соответствует реальным эндпоинтам. Если разработчик добавил параметр в код, но не добавил в схему — пайплайн упадет.
Gramax хранит эти файлы в репозитории, поэтому валидация работает в том же контексте, что и весь остальной CI.
Уведомления при обновлении документации
Когда документация обновляется и мерджится, автоматически отправляется уведомление в нужный канал: «Обновлена документация по /users/settings — посмотри изменения». Это держит команду в курсе без ручных рассылок.
- name: Notify Slack about docs update if: contains(github.event.head_commit.modified, 'docs/') uses: slackapi/slack-github-action@v1 with: payload: | {"text": "📄 Документация обновлена: ${{ github.event.head_commit.message }}\n${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}"}
Автоматическая разметка «устаревшей» документации
Если файл в /docs/ не обновлялся более 90 дней, а соответствующий код — менялся, CI добавляет в документ автоматический баннер «Эта страница может быть устаревшей». Это честнее, чем притворяться, что все актуально.
Что это меняет в команде
Главное, что дает эта связка — исчезает проблема «чья это документация». Она не аналитика, не разработчика и не техписа. Она общая. Каждый работает с ней через свой инструмент, но все смотрят на один и тот же контент в одном репозитории.
Аналитик пишет спецификацию в удобном визуальном редакторе — и не думает про Git. Разработчик читает и правит документ прямо в IDE — и не переключается между инструментами. Техпис полирует готовый текст в визуальном редакторе — и видит актуальную версию, а не то, что разработчик забыл обновить три недели назад. Читатель — коллега или клиент — получает опубликованный результат.