Систематизация знаний на проекте

Все зависит от статуса проекта, но вот примерный план:

Собрать и зафиксировать текущее знание
Структурировать
Убрать противоречия
Поддерживать актуальность

Ключевая задача на входе не «написать документацию», а собрать, структурировать и зафиксировать текущую информацию о системе:

Что система делает сейчас
Почему она делает это именно так
Где находятся основные источники информации
Какие есть ограничения, долги и договорённости

С чего начинать

Где хранится информация

Cоставить список всех мест.

Формальные источники:

Confluence / Notion
Репозиторий (README, ADR, комментарии)
ТЗ, договоры
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. Решения и долги

Известные ограничения
Технический долг
Компромиссы

Как вести документацию дальше

Документируется текущее состояние, а не желаемое
Один раздел → один тип знаний
Любое изменение → обновление документа
Лучше «плохо, но есть», чем «идеально, но никогда»

Практические рекомендации:

Вводить шаблоны
Привязывать документы к задачам
Делать ревью документации с командой

С чего начинать​

Где хранится информация​

Определение границ системы​

Пример структуры проекта​

Подробнее по разделам​

00. Общее​

01. Бизнес-аналитика​

02. Системная аналитика (ядро)​

03. Архитектура​

04. Интеграции​

05. Данные (крайне важен)​

06. API​

07. Нефункциональные требования​

08. Решения и долги​

Как вести документацию дальше​

Материалы​