Где пишешь документацию?

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

1. Markdown-файлы в корне и папках проекта:

• README.md — визитная карточка: описание проекта, быстрый старт, основные зависимости.
• CONTRIBUTING.md — руководство для контрибьюторов.
• CHANGELOG.md — история изменений в формате Keep a Changelog.
• Папка /docs для подробной документации: setup.md, api.md, deployment.md.

2. Инлайн-документирование кода (PHPDoc/JavaDoc):

    /**
     * Рассчитывает итоговую цену заказа с учетом скидки и налогов.
     *
     * @param array<OrderItem> $items Массив товаров в заказе.
     * @param float $discountRate Процент скидки (от 0 до 1).
     * @param string $taxRegion Регион для расчета налога.
     * @return float Итоговая цена.
     * @throws InvalidArgumentException Если процент скидки некорректен.
     * @throws TaxCalculationException Если расчет налога для региона невозможен.
     */
    public function calculateTotalPrice(array $items, float $discountRate, string $taxRegion): float
    {
        // ... реализация
    }

3. Документирование API: Для REST API использую OpenAPI (Swagger). Спецификация в формате YAML/JSON (openapi.yaml) позволяет автоматически генерировать интерактивную документацию (Swagger UI) и клиентские SDK.

4. Архитектурные решения: Важные архитектурные решения фиксирую в формате ADR (Architecture Decision Record) в папке docs/adr/. Это помогает команде понимать контекст принятых решений.

Такой подход обеспечивает актуальность документации, так как ее изменение становится частью code review в пул-реквесте.