Восстановление документации по legacy-системе

Решение

1. Приоритезация документации

Приоритет 1 (КРИТИЧНО — сроки: неделя)

1. Архитектурный обзор системы

   • Диаграмма основных компонентов
   • Взаимодействие между модулями
   • Стек технологий
   • Обоснование: Без этого невозможно ориентироваться в codebase

2. Инструкция по запуску локального окружения

   • Требования к ОС, ПО, версиям
   • Шаги установки
   • Решение типичных проблем
   • Обоснование: Блокирует onboarding новых разработчиков

3. Критические бизнес-процессы

   • Процесс платежа
   • Процесс аутентификации
   • Процесс обработки заказов
   • Обоснование: Ошибка в критических процессах = потеря денег

4. Описание БД: диаграмма ER

   • Основные таблицы и связи
   • Ключевые индексы
   • Важные ограничения
   • Обоснование: БД — это сердце системы

Приоритет 2 (ВАЖНО — сроки: 2 недели)

1. API-документация (Swagger/OpenAPI для всех публичных endpoints)
2. Описание основных модулей (назначение, входные/выходные данные)
3. Процесс развертывания на продакшене
4. Список известных проблем и ограничений
5. Ключевые внешние интеграции (платежные системы, аналитика и т.д.)

Приоритет 3 (ХОРОШО ИМЕТЬ — сроки: месяц)

1. Администраторская документация (как работать с админ-панелью)
2. User scenarios и пошаговые инструкции для основных операций
3. Коды ошибок и их решения
4. Описание бизнес-правил (скидки, комиссии, сроки и т.д.)
5. Глоссарий терминов

Приоритет 4 (ДОПОЛНИТЕЛЬНО — сроки: по мере необходимости)

1. Описание каждого класса/функции (может быть на уровне inline комментариев)
2. История проектных решений (ADR — Architecture Decision Records)
3. Примеры использования API
4. Performance tuning гайды

2. Методы получения информации о системе

Метод 1: Code Mining (анализ исходного кода)

• Инструменты: grep, awk, IDE tools для навигации по коду
• Процесс:
  • Изучить главные точки входа (main, entry point, routes)
  • Проследить key flows вручную через код
  • Идентифицировать паттерны и соглашения
• Результаты: Архитектура, основные компоненты, data flow

Метод 2: Интервью со старыми разработчиками

• Участники: Разработчики, которые писали/поддерживали систему
• Длительность: 1-2 часа на человека
• Вопросы:
  • Почему система реализована именно так?
  • Какие были основные вызовы при разработке?
  • Какие части системы наиболее критичные?
  • Какие проблемы известны?
  • Какие части кода "грязные" и нуждаются в переписывании?
• Результаты: Контекст, обоснование решений, known issues

Метод 3: Reverse Engineering из БД

• Процесс:
  • Экспортировать DDL (Data Definition Language) текущей схемы
  • Создать ER-диаграмму
  • Идентифицировать ключевые таблицы и связи
  • Провести опрос: зачем эта таблица, какие данные там хранятся?
• Результаты: Структура данных, бизнес-сущности

Метод 4: Анализ логов

• Что изучать:
  • Структура логов
  • Основные операции системы
  • Частые ошибки
  • Потоки выполнения
• Результаты: User journeys, процессы, проблемные области

Метод 5: Анализ конфигов

• Файлы: .env, config.yaml, properties файлы и т.д.
• Что выяснять:
  • Какие переменные окружения нужны?
  • Какие режимы работы поддерживаются?
  • Какие интеграции подключены?
• Результаты: Требования к инфраструктуре, конфигурация

Метод 6: Запуск локального окружения + исследование

• Процесс:
  • Установить систему локально
  • Пройти основные операции (логин, создание заказа, платеж)
  • Отслеживать код, логи, БД
  • Документировать то, что видели
• Результаты: Полный user journey, понимание интеграций

Метод 7: Анализ тестов

• Что искать:
  • Unit тесты показывают, как используются компоненты
  • Integration тесты показывают бизнес-сценарии
  • E2E тесты показывают user workflows
• Результаты: Use cases, expected behavior

Метод 8: Интервью с Product Owner / Business

• Участники: Люди, которые знают бизнес-требования
• Вопросы:
  • Какие основные бизнес-процессы?
  • Какие правила и ограничения?
  • Как система зарабатывает деньги?
  • Какие SLA и требования?
• Результаты: Бизнес-логика, требования, метрики успеха

3. Формат и структура документации

Структура папок в репозитории

docs/
├── 01_architecture/
│   ├── overview.md          # Архитектурный обзор
│   ├── components.md        # Описание компонентов
│   ├── data-flow.md         # Потоки данных
│   └── diagrams/
│       ├── architecture.drawio
│       └── database-schema.drawio
├── 02_setup/
│   ├── prerequisites.md     # Требования к окружению
│   ├── local-setup.md       # Как запустить локально
│   ├── docker-compose.yml   # Docker конфиг (если есть)
│   └── troubleshooting.md   # Решение проблем
├── 03_api/
│   ├── overview.md          # Обзор API
│   ├── endpoints.md         # Все endpoints
│   ├── authentication.md    # Аутентификация
│   └── examples.md          # Примеры запросов
├── 04_database/
│   ├── schema.md            # Описание таблиц
│   ├── migrations.md        # История изменений БД
│   └── queries.md           # Важные queries
├── 05_business/
│   ├── processes.md         # Бизнес-процессы
│   ├── glossary.md          # Глоссарий терминов
│   ├── rules.md             # Бизнес-правила
│   └── sla.md               # SLA и требования
├── 06_operations/
│   ├── deployment.md        # Развертывание
│   ├── monitoring.md        # Мониторинг
│   ├── incidents.md         # Как реагировать на инциденты
│   └── backups.md           # Резервное копирование
├── 07_known-issues/
│   ├── limitations.md       # Известные ограничения
│   ├── bugs.md              # Известные баги
│   └── performance.md       # Performance issues
└── README.md                # Главный индекс

Формат документации

Все документы в Markdown с:

• Заголовками (# ## ###)
• Списками (маркированные, нумерованные)
• Кодовыми блоками с синтаксис-хайлайтом
• Диаграммами (ASCII art или external tools: Mermaid, draw.io)
• Таблицами для сравнений
• Ссылками между документами

Шаблон документа

# Заголовок

## Обзор
Описание в 2-3 предложениях, что это и зачем.

## Содержание
- [Раздел 1](#раздел-1)
- [Раздел 2](#раздел-2)

## Раздел 1
...содержание...

## Раздел 2
...содержание...

## Связанные документы
- [Другая документация](./other.md)

## История изменений
- 2024-03-01: Создано
- 2024-03-15: Обновлено с новыми деталями

API-документация

• Формат: OpenAPI 3.0 (Swagger) с auto-generation из кода
• Чтение: https://api.example.com/docs или https://api.example.com/swagger
• Содержит: Все endpoints, параметры, responses, примеры

4. План работ с оценкой сроков

Фаза 1: Быстрый старт (1 неделя)

Итого: 7.5 дней (одна неделя с учётом параллелизма)

Фаза 2: Полнота (2 недели)

Итого: 14 дней (две недели)

Фаза 3: Доработки (2 недели)

Итого: 13 дней (две недели)

Общее время: ~4 недели для полной документации

Методология

• Параллельное выполнение: Несколько людей работают одновременно
• Итеративная доработка: Документация совершенствуется по мере понимания
• Wiki/GitHub: Все в одном месте, версионируется с кодом
• Reviews: Каждый документ рецензируется хотя бы одним другим человеком

5. Метрики качества документации

Метрика 1: Полнота

• Как измерить: Количество описанных компонентов / всего компонентов
• Целевое значение: > 90%
• Проверка: Checklist всех критических компонентов

Метрика 2: Актуальность

• Как измерить: Дата последнего обновления каждого документа
• Целевое значение: Обновление в течение 2 недель после изменения кода
• Проверка: Ежемесячный аудит: какие документы устарели?

Метрика 3: Читаемость

• Как измерить: Опрос новых разработчиков: понятна ли документация?
• Целевое значение: > 80% говорят "да, разобрался за < 1 часа"
• Проверка: Анкета после onboarding

Метрика 4: Наличие примеров

• Как измерить: Количество документов с примерами / всего документов
• Целевое значение: > 70% документов имеют примеры
• Проверка: Автоматический скрипт на наличие блоков ```

Метрика 5: Ссылочность

• Как измерить: Документы, на которые есть cross-references
• Целевое значение: > 70% документов связаны
• Проверка: Граф ссылок между документами

Метрика 6: Скорость onboarding новых разработчиков

• Как измерить: Дни до первого коммита в main
• Базовое значение: Сейчас ~5-7 дней (без документации)
• Целевое значение: < 2 дней (с документацией)
• Проверка: Отслеживаем метрику после каждого найма

Метрика 7: Наличие диаграмм

• Как измерить: Количество диаграмм / число сложных концепций
• Целевое значение: > 50% сложных тем имеют диаграммы
• Проверка: Visual review документов

Метрика 8: Авторитетность (Trust)

• Как измерить: Сколько раз разработчики обращаются к документации вместо кода?
• Целевое значение: > 60% проблем решаются по документации
• Проверка: Логирование обращений к docs/ в вики

6. Инструменты для документирования

• GitHub/GitLab Wiki: Встроенная документация, версионируется с кодом
• Markdown: Простой, универсальный формат
• Mermaid: Диаграммы прямо в Markdown
• Draw.io: Сложные архитектурные диаграммы
• OpenAPI/Swagger: Для API-документации
• Notion/Confluence: Если нужен красивый вид (но может быть несинхронизировано)
• GitBook: Более красивая документация из Git