Какие знаешь виды документации на проекте?

Виды документации на IT-проекте

Документация на проекте — это его нервная система. Плохая документация приводит к потере знаний, дублированию работы и конфликтам между командой. Business Analyst должен знать, какие виды документации существуют и когда какая нужна.

1. Требования и Аналитика

Business Requirements Document (BRD)

Описывает что нужно построить и зачем (бизнес-целей).

Пример:

• Цель: увеличить конверсию на 15% в квартал
• Область влияния: страница оформления заказа
• Требования: добавить одностраничный чекаут, удалить обязательные поля
• Метрики успеха: время до покупки менее 2 минут

Кто пишет: Product Manager, Business Analyst Для кого: Стратегические решения, инвестиции, финансирование

Functional Requirements Specification (FRS)

Описывает как система будет работать с функциональной точки зрения.

Пример функционального требования:

• Система должна позволить пользователю добавить товар в корзину
• При нажатии на кнопку "Добавить" система отправляет POST на /api/cart
• Если товар уже в корзине, увеличится его количество
• Если сервер вернул ошибку, показать сообщение пользователю

Кто пишет: Business Analyst, Senior Developer Для кого: Разработчики, QA, архитекторы

User Stories и Acceptance Criteria

Короткое описание требования с точки зрения пользователя.

As a Customer I want to save my address to profile So that I don't need to enter it every time I checkout

Acceptance Criteria:

• Given: User is logged in
• When: User enters address on checkout page
• Then: System shows "Save address?" button
• And: Clicking it saves address to profile

Кто пишет: Product Owner, Business Analyst Для кого: Sprint планирование, разработка

2. Архитектура и Дизайн

Архитектурная документация

Описывает структуру системы, компоненты и их взаимодействие.

Примеры:

• Диаграммы C4 (Context, Container, Component, Code)
• Диаграммы взаимодействия микросервисов
• Схемы БД (ERD)
• Диаграммы потоков данных (DFD)
• API Specification (OpenAPI/Swagger)

Кто пишет: Software Architect, Lead Developer Для кого: Разработчики, аудиторы, новые члены команды

UI/UX Дизайн

Визуальное описание интерфейса пользователя.

Инструменты: Figma, Adobe XD, Sketch Содержит:

• Wireframes (макет без стилей)
• Prototypes (интерактивные макеты)
• Design System (цвета, шрифты, компоненты)
• User Flows (как пользователь перемещается)

Кто пишет: UI/UX Designer Для кого: Фронтенд-разработчики, QA, стейкхолдеры

3. Процессы и Операции

Процессная документация

Описывает как работает процесс в системе, шаг за шагом.

Пример: Процесс возврата товара

1. Покупатель заполняет форму возврата
2. Система проверяет, прошло ли менее 30 дней
3. Если да: создаёт RMA номер и отправляет письмо
4. Если нет: показывает ошибку
5. После получения товара, warehouse сканирует QR
6. Система запускает возврат денег

Кто пишет: Business Analyst, QA Для кого: Support, разработчики, QA

Операционная документация

Инструкции для поддержки, администраторов и операторов.

Примеры:

• Как обработать возврат вручную
• Как заблокировать пользователя
• Как запустить экспорт данных
• Как восстановиться из бэкапа

Кто пишет: DevOps, Business Analyst Для кого: Support, администраторы, операторы

4. Техническая документация

Код и комментарии

Встроенная документация прямо в исходном коде.

Хороший пример:

function calculateDiscount(price, userLevel) {
  // VIP пользователи получают 20% скидку
  // Расчёт: цена * (1 - уровень * 0.1)
  return price * (1 - userLevel * 0.1);
}

Кто пишет: Разработчики Для кого: Другие разработчики, maintenance

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

Описание всех endpoints, параметров, ответов и ошибок.

Инструменты: Swagger, Postman, Redoc Содержит:

• Описание каждого endpoint (GET, POST, PATCH, DELETE)
• Параметры запроса и ответа
• Примеры запросов и ответов
• Коды ошибок и их значения
• Rate limits

Кто пишет: Backend разработчик, Tech Writer Для кого: Frontend разработчики, интеграторы, мобильные разработчики

Database Schema Documentation

Описание таблиц, полей, индексов и связей.

Таблица: users

• id (UUID, Primary Key)
• email (VARCHAR 255, UNIQUE)
• created_at (TIMESTAMP, DEFAULT NOW())
• is_active (BOOLEAN, DEFAULT true)
• Индекс: (email) для быстрого поиска
• Связь: 1 пользователь → много заказов

Кто пишет: DBA, Backend разработчик Для кого: Разработчики, аналитики

5. Тестирование и Качество

Test Cases и Test Plans

Описание того, что и как тестировать.

Test Case #1: Успешный вход Шаги:

1. Открыть страницу входа
2. Ввести email test@example.com
3. Ввести пароль pass123
4. Нажать "Войти"

Ожидаемый результат: пользователь вошёл, видит личный кабинет

Кто пишет: QA, Business Analyst Для кого: QA инженеры, разработчики

6. Обучение и Support

User Manual и Knowledge Base

Инструкции для конечных пользователей.

Примеры:

• Как создать аккаунт
• Часто задаваемые вопросы
• Видеотуториалы
• Контакты support

Кто пишет: Tech Writer, Support Manager Для кого: Конечные пользователи, support команда

Training Materials

Обучающие материалы для внутренних команд.

Кто пишет: Product Manager, Business Analyst Для кого: Новые сотрудники, команда support

Какую документацию приоритизировать

Критична (делай первым)

1. User Stories и Acceptance Criteria
2. API документация
3. Database Schema
4. Процессная документация

Важна (делай по мере времени)

1. Архитектурная документация
2. Операционная документация
3. Test Cases

Желательна (поддерживай актуальной)

1. BRD и FRS
2. User Manual
3. Комментарии в коде

Золотое правило

Лучше немного документации, но актуальной, чем много старой и неправильной.

Документация должна обновляться вместе с кодом. Если требование изменилось, немедленно обновляй документацию, иначе она станет источником ошибок.