Это документ для разработчиков, которые будут дорабатывать, поддерживать или интегрироваться с системой. Его цель — дать быстрый старт в коде, раскрыть архитектурные решения и описать «неочевидные» места, которые не видны из самого кода.
Основные разделы
- Назначение и область применения. Кратко: что делает система, какие задачи закрывает, в каком контексте используется (внутренний сервис, публичное API, компонент платформы). Указывают ключевые ограничения и допущения.
- Архитектура и высокоуровневая структура. Описание слоёв (API, бизнес‑логика, доступ к данным), основных компонентов и их ответственности. Сюда включают диаграммы (C4, UML component/sequence) и обоснование выбора технологий и паттернов.
- Технологический стек и зависимости. Версии языков, фреймворков, библиотек, системных требований. Отдельно фиксируют критические зависимости и их ограничения по совместимости.
- Структура проекта и организация кода. Как устроены папки и модули, принципы именования, правила разделения кода (например, «всё, что связано с платежами — в папке payments»). Для монорепозиториев добавляют описание пакетов и связей между ними.
- Настройка окружения и локальная разработка. Пошагово: установка зависимостей, переменные окружения, подключение к тестовым базам и сервисам, запуск приложения и тестов. Включают скрипты и типовые проблемы с решениями.
- Процедуры сборки и деплоя. Команды и пайплайны для CI/CD, профили сборки (dev/stage/prod), миграции БД, управление секретами. Если есть кастомные скрипты — дают примеры и описание параметров.
- API и внутренние интерфейсы. Для внешних вызовов — спецификация (OpenAPI/Swagger), для внутренних — описание контрактов, форматов сообщений, правил версионирования и обратной совместимости.
- Входные и выходные данные. Форматы запросов/ответов, схемы данных (JSON Schema, Protobuf, XSD), правила валидации, кодировки, обработка ошибок и коды статусов.
- Обработка ошибок и логирование. Какие исключения считаются критичными, какие можно игнорировать, как формируются сообщения об ошибках. Указывают уровни логирования, формат логов, куда они пишутся и как их фильтровать.
- Тестирование. Где лежат тесты, как их запускать, какие виды тестов есть (юнит, интеграционные, E2E), как готовить тестовые данные и моки.
- Нефункциональные требования и ограничения. Производительность (SLA по времени ответа), лимиты (rate limits, размеры файлов), требования к безопасности (шифрование, токены, CORS), отказоустойчивость и повторные попытки.
- Глоссарий и термины. Специфичные для проекта понятия и аббревиатуры с расшифровкой, чтобы избежать разночтений.
- Приложения и примеры. Типичные сценарии использования, фрагменты кода (на 1–3 языка), примеры запросов/ответов, дампы миграций, чек‑листы для ревью и релиза.
Особенности в зависимости от формата
- По ГОСТ 19.504‑79 (для госзаказов и регламентированных проектов). Строгая структура: назначение и условия применения, характеристики программы, обращение к программе, входные/выходные данные, сообщения. Акцент на формальные реквизиты, однозначные формулировки и контроль версий.
- В Agile‑ и продуктовых командах. Делают упор на «быстрый вход»: максимум примеров, скриптов и ссылок (на репозиторий, CI, дизайн‑систему). Часть информации хранят в README.md, CONTRIBUTING.md и wiki, а не в едином документе.
- Для библиотек и SDK. Ключевое — примеры кода, сценарии интеграции, обработка краевых случаев и миграции между версиями. Часто используют автогенерируемую документацию (Doxygen, Sphinx, Javadoc) плюс ручные гайды.
Принципы написания
- Ориентируйтесь на нового разработчика. Представьте, что человек пришёл в проект сегодня и должен через 2–4 часа запустить сервис и сделать первый коммит. Всё, что ему для этого нужно, должно быть в руководстве.
- Пишите исполняемые инструкции. Вместо «настройте базу данных» — конкретные шаги и команды, переменные окружения с примерами значений (или шаблонами), ссылки на тестовые дампы.
- Держите актуальность. Назначьте владельца документа, ведите changelog, синхронизируйте с README и CI‑скриптами. Если инструкция перестала работать — это баг.
- Используйте автоматизацию. API‑документацию генерируйте из кода, схемы — из PlantUML/Mermaid, примеры — из реальных тестов. Это снижает расхождение между описанием и реализацией.
- Добавляйте «подводные камни». Описывайте неочевидные моменты: таймауты, особенности кэширования, зависимости от внешних сервисов, известные проблемы и временные решения.
Форматы и инструменты
- Markdown (README.md, docs/). Самый распространённый вариант: хранится в репозитории, версионируется вместе с кодом, легко читается в IDE и на GitHub/GitLab.
- Confluence, Notion. Для больших проектов и команд, где нужна ролевая модель, комментарии и поиск по документам.
- GitBook, ReadTheDocs. Для публикации красивой документации как сайта с оглавлением, поиском и версиями.
- Doxygen, Sphinx, Javadoc. Автогенерация из комментариев в коде для библиотек, SDK и низкоуровневых компонентов.
- PlantUML, Mermaid. Диаграммы прямо в тексте документации: их проще поддерживать и обновлять.