Методология документирования¶
Принципы и правила написания документации.
Ключевой принцип¶
Документация описывает бизнес-логику системы. Product-слой и кодовая база синхронизируются двусторонне. При расхождении — выясняется актуальное состояние и синхронизируется.
Структура¶
source/
├── product/ # ЧТО делает система (бизнес-логика)
└── methodology/ # Правила написания документации
Матрица выбора слоя¶
| Пишу о... | Слой | Пример |
|---|---|---|
| Бизнес-логика, User Stories | product/ |
"Игрок выбирает числа" |
| Таблицы выплат, формулы | product/math/ |
"5 совпадений = 38.80x" |
| JSON-схемы API | game-api |
{ player_id, amount } |
| Sequence diagrams | game-api |
Frontend → Backend → Wallet |
| Сервисы и их роли | game-api |
"Game Backend владеет раундами" |
Быстрый старт¶
Product-документация:
- Фокус на "что" и "зачем"
- User Stories с Acceptance Criteria
- Без JSON-схем и таблиц коэффициентов
Technical-документация:
- Ссылается на product/ для бизнес-контекста
- Использует абстрактные термины (кеш, не Redis)
- JSON-схемы, sequence diagrams, формулы
Подробнее¶
- Полное руководство — все правила и примеры
- MVP Scope — scope проекта
Sales / pre-call prep¶
Материалы для подготовки к звонкам с интеграторами / агрегаторами / операторами. Два документа под две аудитории:
| Документ | Кто читает | Когда |
|---|---|---|
| CEO Call Checklist | Founder / CTO / sales lead | До звонка, при подготовке CEO |
| CEO Call Cheat Sheet | CEO (нетехнический) | Во время звонка |
Шпаргалка — простыми словами, без жаргона: готовые фразы по типу «если они скажут X — отвечаем Y», аналогии для каждого термина, честные ответы на вопросы-ловушки.
Чеклист — глубокий prep-материал на ~250 пунктов в 24 разделах, содержит технические подробности и ссылки на ADR'ы.
Незнакомые термины — в основном глоссарии.
Метки в чеклисте:
[GAP]— известное ограничение продукта (проговорить контрагенту)[POLICY?]— нет утверждённой позиции, требует решения CEO до звонка[ОРИЕНТИР]— индустриальный baseline, не наше обязательство