Как вы поддерживаете актуальность документации при частых изменениях требований?

Поддержание актуальности документации при изменении требований

Одна из главных проблем в проектах — это рассинхронизация документации и реального состояния кода. Требования меняются, но документация остаётся старой. Вот практические методы, которые работают.

Проблема: Устаревшая документация

Почему это происходит:

• Разработчики торопятся, не обновляют документацию
• Много изменений, документация не успевает
• Никто не проверяет актуальность
• Документация в отдельном месте от кода

Последствия:

• Новые разработчики зависят от старой информации
• Ошибки при интеграции
• Потерянное время на выяснение "как это работает на самом деле"
• Высокие издержки на поддержку

1. Документация в коде (Living Documentation)

Суть: Документация должна быть максимально близко к коду.

Код-комментарии и Doc-блоки

Python (docstrings):

def get_user_by_email(email: str) -> User:
    """Get user by email address.
    
    Args:
        email: User's email address (must be valid format)
        
    Returns:
        User object if found
        
    Raises:
        UserNotFound: If email not in system
        InvalidEmail: If email format is invalid
        
    Example:
        >>> user = get_user_by_email("john@example.com")
        >>> user.name
        'John Doe'
    """
    # Валидация email
    if not is_valid_email(email):
        raise InvalidEmail(f"Invalid email: {email}")
    
    # Поиск в БД
    user = db.query(User).filter_by(email=email).first()
    if not user:
        raise UserNotFound(f"User {email} not found")
    
    return user

TypeScript:

/**
 * Create a new order for the user
 * @param userId - ID of the user placing the order
 * @param items - Array of product IDs and quantities
 * @param shippingAddress - Delivery address
 * @returns Order object with ID and total price
 * @throws {InvalidItemError} If product doesn't exist
 * @throws {InsufficientStockError} If not enough inventory
 * 
 * @example
 * const order = await createOrder('user123', [{id: 'prod1', qty: 2}], {...});
 */
async function createOrder(
  userId: string,
  items: OrderItem[],
  shippingAddress: Address
): Promise<Order> {
  // Validation and logic
}

Преимущества:

• Документация рядом с кодом
• IDE автоматически показывает при hover
• Если код меняется, есть вероятность обновить комментарий

README для каждого модуля

project/
├── src/
│   ├── auth/
│   │   ├── README.md       ← Документация модуля
│   │   ├── service.py
│   │   ├── models.py
│   │   └── tests/
│   ├── orders/
│   │   ├── README.md       ← Документация модуля
│   │   ├── service.py
│   │   └── ...

auth/README.md:

# Authentication Service

## Overview
Handles user authentication, JWT token generation, and OAuth integration.

## Key Components
- `AuthService` - Main authentication logic
- `TokenManager` - JWT token lifecycle
- `OAuthProvider` - External OAuth providers

## API Endpoints
- POST /auth/login - Authenticate user
- POST /auth/refresh - Refresh JWT token
- POST /auth/logout - Invalidate token

## Database Schema
- `users` table - User accounts
- `oauth_providers` table - OAuth integrations

## Configuration
- JWT_SECRET: Secret for signing tokens
- TOKEN_EXPIRY: Token expiration time (default: 24h)

2. Версионирование документации в Git

Суть: Держать документацию в том же репозитории, что и код.

project/
├── src/           (исходный код)
├── docs/          (документация)
│   ├── index.md
│   ├── architecture/
│   │   ├── 01_overview.md
│   │   ├── 02_decisions.md
│   │   └── 03_data_model.md
│   ├── api/
│   │   ├── users.md
│   │   ├── orders.md
│   │   └── payments.md
│   ├── guides/
│   │   ├── setup.md
│   │   ├── deployment.md
│   │   └── testing.md
├── CHANGELOG.md
├── README.md
└── .git

Преимущества:

• История всех изменений видна в git log
• Code review перед коммитом может проверить документацию
• Diff показывает, что изменилось в требованиях
• Можно откатить вместе с кодом

Пример commit'а:

commit 3a7c9f2
Author: John <john@example.com>
Date:   Fri Mar 28 10:30:00 2025

    feat(auth): Add two-factor authentication
    
    - Add TOTP support
    - Update user schema with secret key
    - Update API docs with 2FA endpoints
    
    Docs changes:
    - Updated docs/api/users.md with new endpoints
    - Updated architecture decision in docs/architecture/02_decisions.md

Всё видно в истории!

3. Автоматическое генерирование документации

API Documentation из кода

OpenAPI / Swagger:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(
    title="E-commerce API",
    version="1.0.0",
    description="API для управления заказами"
)

class User(BaseModel):
    """User model"""
    id: int
    name: str
    email: str

@app.post("/users", response_model=User)
async def create_user(
    name: str,
    email: str
) -> User:
    """Create a new user.
    
    Args:
        name: User's full name
        email: User's email address
        
    Returns:
        Created user object
    """
    # Implementation
    pass

# Автоматически генерирует Swagger UI на /docs

Документация создаётся автоматически из кода! Если меняешь параметры — меняется и документация.

GraphQL Schema:

"""User in the system"""
type User {
  """Unique identifier"""
  id: ID!
  
  """User's email address"""
  email: String!
  
  """User's display name"""
  name: String!
}

"""Query root"""
type Query {
  """Get user by ID"""
  user(id: ID!): User
}

GraphQL schema — это документация и код одновременно.

Database Schema из миграций

Если используешь Goose (миграции), структура БД — это документация:

-- File: migrations/0001_create_users_table.sql

CREATE TABLE users (
    id UUID PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    name VARCHAR(255) NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now(),
    updated_at TIMESTAMPTZ DEFAULT now()
);

CREATE INDEX idx_users_email ON users(email);

-- Если читаешь миграции — видишь точно, какая у нас схема

4. Тесты как документация (Executable Documentation)

Суть: Тесты — это живая документация, которая всегда актуальна.

def test_user_can_place_order():
    """
    Scenario: User places an order
    Given: User has items in cart
    When: User clicks "Place Order"
    Then: Order is created with status "pending"
    And: Payment service is called
    And: User receives confirmation email
    """
    # Setup
    user = create_test_user(email="john@test.com")
    product = create_test_product(name="Laptop", price=999.99)
    
    # Action
    order = user.add_to_cart(product)
    result = user.place_order()
    
    # Verify
    assert result.status == OrderStatus.PENDING
    assert order.total == 999.99
    
    # Check side effects
    assert mock_payment_service.called
    assert mock_email_service.called
    assert mock_email_service.last_call.recipient == "john@test.com"

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

5. Change Log и Release Notes

CHANGELOG.md:

# Changelog

## [Unreleased]
- New: Two-factor authentication
- Changed: Order status workflow (added "partially_shipped")
- Fixed: Bug with duplicate orders
- Deprecated: Old payment API v1 (use v2)

## [2.1.0] - 2025-03-28
### Added
- Two-factor authentication support
- New endpoints for user preferences

### Changed
- Improved order processing performance
- Updated payment provider to Stripe v2

### Fixed
- Race condition in inventory check

### Removed
- Legacy XML API support

Это автоматически генерируется из commit messages (если использовать Conventional Commits):

feat(auth): Add two-factor authentication
         ↓ автоматически попадёт в "Added" секцию

fix(order): Race condition in inventory
         ↓ автоматически попадёт в "Fixed" секцию

breaking: Remove XML API
         ↓ автоматически попадёт в "Removed" секцию

6. Architecture Decision Records (ADR)

Суть: Фиксируем важные архитектурные решения с причинами.

docs/architecture/ADR-001-use-microservices.md:

# ADR-001: Использование микросервисной архитектуры

## Status
Accepted (Принято)

## Context
Монолитное приложение растёт, стало сложно масштабировать отдельные компоненты.
Разные команды хотят разные стеки технологий.

## Decision
Мигрируем на микросервисную архитектуру.

## Rationale
- Независимое масштабирование
- Разные команды могут использовать разные стеки
- Меньше merge conflicts
- Лучше для DevOps

## Consequences
+ Лучше масштабируемость
- Сложнее локально разворачивать
- Больше сетевых запросов
- Нужна инфраструктура для координации

## Alternatives
- Остаться в монолите (отвергнуто: не решает проблему роста)
- Использовать модульный монолит (отвергнуто: не достаточно)

Теперь будущие разработчики знают:

• Почему мы выбрали микросервисы
• Какие были альтернативы
• Какие сложности ожидать

7. Регулярные аудиты документации

Процесс:

1. Eachทมีmeeting (weekly):

   • 15 минут обзора, что изменилось
   • Обновляем документацию

2. Sprint Review:

   • Проверяем, все ли требования документированы
   • Обновляем диаграммы

3. Quarterly Documentation Audit:

   • Прочитать всю документацию
   • Проверить на актуальность
   • Удалить устаревшее

4. Code Review для документации:

   Обычный Code Review:
   - Проверяем код
   - Смотрим тесты
   
   + Документирующий Code Review:
   - Проверяем документацию
   - Смотрим комментарии в коде
   - Проверяем, обновлены ли API доки
   

8. Инструменты для синхронизации

Wiki (Confluence, Notion)

• Ссылаются на GitHub issues
• Автоматически обновляются из CI/CD

Doc generation tools

• MkDocs — генерирует сайт из Markdown
• Sphinx (Python) — документация из docstrings
• Swagger/OpenAPI — API документация из аннотаций
• Storybook (React) — документация компонентов с примерами

9. Определение ответственности

Кто обновляет документацию:

Правило: Тот, кто меняет функционал, должен обновить документацию.

10. Проверка актуальности в CI/CD

Automation:

# .github/workflows/docs-check.yml
name: Documentation Check

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Check if docs are updated
        run: |
          # Если изменился src/, должна измениться docs/
          changed_src=$(git diff --name-only ${{ github.base_ref }}...HEAD -- src/)
          changed_docs=$(git diff --name-only ${{ github.base_ref }}...HEAD -- docs/)
          
          if [ -n "$changed_src" ] && [ -z "$changed_docs" ]; then
            echo "❌ Код изменен, но документация не обновлена!"
            exit 1
          fi
          echo "✅ Документация актуальна"

Практический пример: Workflow при изменении

Сценарий: Разработчик добавляет новый endpoint

1. Разработчик пишет код:
   POST /api/users/123/profile

2. Обновляет docstring:
   def update_user_profile(user_id: str, data: ProfileUpdate):
       """Update user profile
       ...
       """

3. Swagger/OpenAPI автоматически обновляет API docs
   (заходим на /api/docs — там новый endpoint)

4. Пишет тест:
   def test_update_user_profile():
       """User can update their profile"""
       # Тест является документацией

5. Обновляет API документацию в Confluence/docs/
   (если нужны примеры, rate limits и т.д.)

6. Обновляет CHANGELOG.md:
   - New: PUT /api/users/{id}/profile endpoint

7. Code Review смотрит:
   ✅ Код
   ✅ Тесты
   ✅ Docstring
   ✅ CHANGELOG.md
   ✅ API docs
   → Одобрить

Заключение

Главный принцип: Документация должна быть максимально близка к коду. Чем дальше, тем больше вероятность, что она устареет.

Рекомендуемый набор:

1. Docstrings в коде (ОБЯЗАТЕЛЬНО)
2. Tests как живая документация (ОБЯЗАТЕЛЬНО)
3. README.md в каждом модуле (ОБЯЗАТЕЛЬНО)
4. API docs (Swagger/OpenAPI) — автоматизировано (ОБЯЗАТЕЛЬНО)
5. Git history как версионирование документации (ОБЯЗАТЕЛЬНО)
6. Architecture Decision Records для больших решений (ХОРОШО)
7. CHANGELOG.md из commit messages (ХОРОШО)
8. Confluence/Wiki для сложной документации (ОПЦИОНАЛЬНО)