Техническая документация
API-документация, архитектурные записи, руководства и ранбуки со структурированным ревью.
Обзор
API-документация, записи архитектурных решений, руководства пользователя и ранбуки — все они выигрывают от структурированного процесса создания и проверки. Datarim гарантирует точность, полноту и верифицированность документации по реальным системам. Пайплайн предотвращает типичную ситуацию, когда документация пишется один раз и никогда не проверяется — каждый эндпоинт проверен, каждый пример протестирован, каждая ссылка валидна.
Пример: документация API платёжного сервиса
Команде нужно создать полную API-документацию для сервиса обработки платежей с 12 эндпоинтами. Документация предназначена для сторонних интеграторов и должна включать рабочие примеры кода на трёх языках программирования.
Прохождение пайплайна
| Этап | Что происходит |
|---|---|
| /dr-init | Рамки: 12 эндпоинтов, схемы запросов/ответов, коды ошибок, поток аутентификации (L2) |
| /dr-prd | Аудитория: сторонние интеграторы. Требования: OpenAPI 3.1, примеры кода на 3 языках, URL песочницы |
| /dr-plan | Приоритет: сначала поток аутентификации, затем жизненный цикл платежа (создание → захват → возврат), потом вебхуки |
| /dr-do | Написание документации. Перекрёстная проверка с реальным кодом API |
| /dr-qa | Проверка: все эндпоинты задокументированы, примеры протестированы, коды ошибок полны, ссылки валидны |
| /dr-archive (Step 0.5) | Вывод: генерация примеров из реальных ответов API оказалась быстрее ручного написания |
Ключевые преимущества
- Точность через перекрёстную проверку — документация верифицируется по реальному коду API, а не по предположениям о поведении
- Проектирование от аудитории — на этапе PRD определяется, кто читает документацию и что им нужно
- Протестированные примеры — QA гарантирует работоспособность каждого примера кода на каждом языке
- Живая документация — пайплайн можно перезапустить при изменениях API, и QA обнаружит устаревшие разделы
Задействованные агенты
Какие агенты наиболее активны в этом сценарии:
- Writer — создание документации с чёткой структурой и примерами
- Editor — проверка единообразия, терминологии и форматирования
- Developer — верификация примеров кода и сверка с исходным кодом
- Reviewer — проверка полноты и валидация ссылок
Маршрутизация по сложности
Как уровни сложности применяются к технической документации:
- L1 — Обновить описание эндпоинта или исправить нерабочий пример кода
- L2 — Задокументировать новый API с 10-15 эндпоинтами, включая схемы и примеры
- L3 — Создать полный портал разработчика с гайдами, туториалами и справочной документацией
- L4 — Документация для нескольких продуктов с версионированием, гайдами миграции и описанием SDK