Все зависит от статуса проекта, но вот примерный план:
🤩собрать и зафиксировать текущее знание
🤩структурировать
🤩убрать противоречия
🤩поддерживать актуальность
Ключевая задача на входе не «написать документацию»,
а собрать, структурировать и зафиксировать текущую инфу о системе:
🔣что система делает сейчас
🔣почему она делает это именно так
🔣где находятся основные источники информации
🔣какие есть ограничения, долги и договорённости
С чего начинать
Где хранится информация: составить список всех мест
Формальные:
⚪️ Confluence / Notion
⚪️ репозиторий (README, ADR, comments)
⚪️ ТЗ, договоры
⚪️ API-спецификации (Swagger, Postman)
⚪️ BPMN / схемы / презентации
Неформальные:
⚪️знания разработчиков
⚪️чаты
⚪️комментарии в тасках
⚪️личные файлы коллег
Определение границ системы
❓ что является нашей системой, а что — внешним контуром
❓ кто основные пользователи
❓ какие внешние системы интегрированы
❓ где начинается и где заканчивается ответственность команды
Это основа будущей контекстной диаграммы (C4)
Пример структуры проекта
📌 Лучше разделять бизнес и системную аналитику
Важно для масштабируемости
Пример верхнеуровневой структуры
/Проект
/00_Общее
/01_Бизнес-аналитика
/02_Системная_аналитика
/03_Архитектура
/04_Интеграции
/05_Данные
/06_API
/07_НФТ
/08_Решения_и_долги
Подробнее по разделам
✨ 00. Общее
Дать понимание проекта за короткий срок
Описание проекта (1–2 страницы):
➖зачем система существует, для кого
➖какую бизнес-проблему решает
➖глоссарий
➖участники
➖актуальные источники: где документация, код, API
✨ 01. Бизнес-аналитика
Фиксирует что и зачем делает система, без привязки к реализации
Пример структуры
/01_Бизнес-аналитика
/01_Цели_и_метрики
/02_Бизнес-процессы
/03_Роли_и_пользователи
/04_Бизнес-правила
/05_Сценарии_использования
Бизнес-процессы:
⚪️AS-IS (как есть сейчас)
⚪️TO-BE (если планируется развитие)
⚪️BPMN или текст + диаграммы
Use Cases / User Stories: без технических деталей
✨ 02. Системная аналитика (ядро)
Как именно система работает сейчас
Пример структуры
/02_Системная_аналитика
/01_Функциональные_требования
/02_Сценарии_и_алгоритмы
/03_Состояния_и_статусы
/04_Валидации_и_ошибки
Что важно
➖детальные сценарии
➖условия, ветвления
➖бизнес-правила в формализованном виде
➖краевые кейсы
✨03. Архитектура
➖C4 диаграмма
➖описание основных компонентов
➖ответственность сервисов
➖очереди, кэши, БД
✨ 04. Интеграции
Для каждой интеграции:
➖назначение
➖инициатор
➖формат данных
➖синхрон / асинхрон
➖ошибки и ретраи
✨05. Данные (крайне важен)
➖ER-диаграммы
➖описание ключевых сущностей
➖статусы и их жизненный цикл
➖источники данных
✨ 06. API
➖Swagger / OpenAPI
➖описание эндпоинтов в бизнес-терминах
➖примеры сценариев
✨07. Нефункциональные требования
➖производительность
➖безопасность
➖SLA
➖логирование
✨08. Решения и долги
➖известные ограничения
➖технический долг
➖компромиссы
Как вести документацию дальше
⚪️ документируется текущее состояние, а не желаемое
⚪️ один раздел → один тип знаний
⚪️ любое изменение → обновление документа
⚪️ лучше «плохо, но есть», чем «идеально, но никогда»
Практика
⚪️вводить шаблоны
⚪️привязывать документы к задачам
⚪️делать ревью документации с командой
🔹 Подборка шаблонов документации
➿➿➿➿➿➿➿➿
🧑🎓 Больше полезного в базе знаний по системному анализу