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

Документация, которую я создавал на проектах

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

Функциональные требования (Functional Requirements Document, FRD)

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

Что включает:

• Обзор — краткое описание функциональности
• Бизнес-требования — что нужно достичь
• Пользовательские сценарии — конкретные use case'ы
• Функции — детальное описание каждой функции
• Экраны/Макеты — UI дизайн
• Бизнес-правила — какие правила применяются
• Примеры — конкретные примеры того, как это работает

Пример структуры:

1. Введение
2. Обзор системы
3. Пользовательские роли
4. Сценарии использования
   4.1 Сценарий 1: Создание заказа
       - Предусловия
       - Основной поток
       - Альтернативные потоки
       - Результат
   4.2 Сценарий 2: ...
5. Функциональные требования
   5.1 Модуль 1
   5.2 Модуль 2
6. Интеграции
7. Аппендикс (диаграммы, глоссарий)

Когда использую: Обычно для крупных проектов или Waterfall подходов.

SRS (Software Requirements Specification)

Формальный документ, часто требуемый в государственных и крупных коммерческих проектах.

Что включает:

• Все функциональные требования
• Нефункциональные требования (performance, security, scalability)
• Ограничения
• Допущения
• Зависимости

Объем: Может быть 100-300 страниц для больших систем.

Когда использую:

• Проекты с фиксированной ценой
• Государственные контракты
• Системы, критичные по надёжности

Product Requirements Document (PRD)

Менее формальный, но очень практичный для Agile проектов.

Что включает:

• Что — какая функциональность
• Почему — бизнес-обоснование
• Кто — целевые пользователи
• Когда — timeline
• Метрики успеха — как мы поймём, что это работает

Объем: Обычно 5-20 страниц.

Пример:

# Feature: Two-Factor Authentication

## Objective
Улучшить безопасность учётных записей пользователей.

## Business Metrics
- Уменьшить хаки на 80%
- Увеличить engagement на 5%

## User Stories
- As a user, I want to enable 2FA so that my account is secure
- As a user, I want to receive SMS codes so that I can verify login

## Technical Requirements
- SMS API integration
- Database schema changes
- UI for 2FA setup

## Success Criteria
- 50% users enable 2FA in month 1
- Support requests decrease

Когда использую: Большинство современных проектов.

Use Case Documents

Документы, описывающие взаимодействие пользователя с системой.

Структура:

Use Case: "Создание заказа"
Актер: Покупатель
Предусловие: Пользователь авторизован

Основной поток:
1. Пользователь выбирает товары
2. Пользователь заполняет адрес доставки
3. Система проверяет адрес
4. Пользователь выбирает способ оплаты
5. Система создаёт заказ
6. Система показывает подтверждение

Альтернативный поток 1 (адрес невалидный):
3a. Адрес не прошёл валидацию
3b. Система показывает ошибку
3c. Пользователь вводит новый адрес

Постусловие: Заказ создан, пользователю отправлено письмо

Когда использую: Когда нужно явно описать пользовательский сценарий.

API Documentation

Документация для интеграций и для фронтенд разработчиков.

Что включает:

• Endpoints — URL и методы
• Параметры — input parameters
• Ответы — output format
• Ошибки — какие ошибки могут быть
• Примеры — curl примеры
• Rate limiting — ограничения

Инструменты:

• Swagger/OpenAPI
• Postman
• API Blueprint
• Confluence + примеры

Пример:

GET /api/v1/orders/{id}

Response: 200 OK
{
  "id": "123",
  "user_id": "456",
  "status": "shipped",
  "total": 99.99,
  "items": [...],
  "created_at": "2024-01-15T10:30:00Z"
}

Error: 404 Not Found
{
  "error": "Order not found"
}

Когда использую: На каждом проекте с внешними интеграциями.

Data Dictionary / Glossary

Определение всех терминов, которые используются в проекте.

Пример:

Термин: Status
Определение: Текущее состояние заказа
Возможные значения: pending, processing, shipped, delivered, cancelled
Ответственный: Order Service

Термин: SKU
Определение: Stock Keeping Unit — уникальный идентификатор товара
Пример: ABC-123-XL-RED
Источник: Inventory Management System

Когда использую: Всегда создаю для крупных проектов.

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

Что включает:

• High-level диаграмма — общая архитектура
• Компоненты — какие компоненты участвуют
• Интеграции — как компоненты взаимодействуют
• Data flow — как данные текут через систему
• Решения — архитектурные решения и их обоснование

Инструменты:

• C4 model диаграммы
• Architecture Decision Records (ADR)
• Draw.io

Когда использую: При проектировании новой системы или значительных изменениях.

Test Case Documentation

Документация для QA, описывающая, что нужно тестировать.

Структура:

Тест-кейс: TC-001
Название: Valid order creation
Предусловие: User is logged in

Шаги:
1. Navigate to orders page
2. Click "Create order"
3. Select 2 items
4. Fill shipping address: "123 Main St"
5. Select payment method: "Credit Card"
6. Click "Confirm"

Ожидаемый результат:
- Order created with status "pending"
- Confirmation email sent
- Order appears in user's order list

Актуальный результат: [заполняет QA]

Когда использую: Обычно работаю с QA командой для создания.

Change Log и Release Notes

Документация изменений между версиями.

Пример:

## Version 2.1.0 (2024-01-20)

### Features
- Added two-factor authentication
- New dashboard with analytics
- Email notifications

### Bug Fixes
- Fixed login timeout issue (JIRA-123)
- Corrected calculation in invoice (JIRA-124)

### Breaking Changes
- Removed deprecated /api/v1/old-endpoint
- Changed response format for /orders endpoint

### Migration Guide
Users upgrading from 2.0.x should...

Когда использую: При каждом релизе.

Training Documentation

Документация для обучения пользователей.

Что включает:

• Getting started — первые шаги
• User guide — как использовать функции
• FAQ — часто задаваемые вопросы
• Troubleshooting — решение проблем
• Screenshots — визуальное руководство
• Videos — обучающие видео

Когда использую: Перед запуском системы.

Decision Records (ADR)

Документ, описывающий архитектурное решение и его обоснование.

Структура:

# ADR 001: Use REST API instead of GraphQL

## Status
Accepted

## Context
Мы выбирали между REST и GraphQL для нашего API.

## Decision
Мы выбрали REST API.

## Consequences

Позитивные:
- Проще для разработчиков (большинство знают REST)
- Лучше кэшируется
- Меньше learning curve

Негативные:
- Over-fetching в некоторых случаях
- Требует versioning

## Alternatives Considered
- GraphQL (rejected: higher complexity)
- gRPC (rejected: not suitable for web)

Когда использую: При выборе важных технических решений.

Мой подход к документированию

Принципы:

1. Достаточно, но не избыточно — создаю столько, сколько нужно, не больше
2. Живая документация — поддерживаю в актуальном состоянии
3. Примеры, примеры, примеры — пример лучше тысячи слов
4. Разные форматы для разных аудиторий:
   • Для бизнеса: PRD с метриками и ROI
   • Для разработчиков: API docs и архитектурные диаграммы
   • Для QA: тест-кейсы и сценарии
   • Для пользователей: обучающие материалы
5. Контроль версий — документы в Git когда возможно

Инструменты, которые я использую

• Confluence — для wiki документации
• Google Docs — для совместного редактирования
• Markdown + Git — для технической документации
• Draw.io — для диаграмм
• Swagger/OpenAPI — для API
• Notion — для product documentation

Главное правило

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