Документация: писать так, чтобы читали

Документация — это коммуникация с будущими людьми, включая вас через полгода. Учимся писать полезные README и заметки.

Хорошая документация отвечает на вопрос читателя быстрее, чем он успел бы спросить коллегу или прочитать код.

Зачем документировать

«Код — лучшая документация» верно лишь отчасти: код говорит как, но не почему. Почему выбрали именно эту библиотеку, почему здесь костыль, почему нельзя удалить странную строку — это знание живёт в голове автора и теряется, когда он уходит. Документация сохраняет контекст.

Что документировать в первую очередь

Документируйте	Можно не документировать
как запустить проект с нуля	что делает очевидная строка кода
неочевидные решения и их причины	стандартный синтаксис языка
«грабли» и обходные пути	то, что и так видно из имён
контракты API, форматы данных	временный отладочный код

Структура README

# Название проекта
Одно предложение: что это и зачем.

## Быстрый старт
команды, чтобы поднять локально за 5 минут

## Как это устроено
краткая карта: основные части и как связаны

## Частые проблемы
известные грабли и решения

## Кому писать
ответственные/контакты

Пишите для конкретного читателя

Перед тем как писать, спросите: кто это прочитает и в какой ситуации? README для новичка в команде — это «как запустить и не сломать». Доклад для архитекторов — «какие решения и компромиссы». Один текст не покрывает всех, поэтому определите аудиторию заранее.

Как работает под капотом

Документацию читают не подряд, а по диагонали в поиске ответа. Поэтому работают: говорящие заголовки (по ним сканируют), короткие абзацы, списки, примеры. Стена текста без структуры не читается — её закрывают. Главный критерий полезности: может ли новый человек по вашему README поднять проект сам, не дёргая вас? Если нет — документация не выполнила задачу.

Документация устаревает — и это опасно

Неверная документация хуже отсутствующей: она уводит в ложном направлении. Поэтому правило: меняешь поведение — обнови описание в том же PR. Документацию держите рядом с кодом (в репозитории), чтобы она менялась вместе с ним.

Частые ошибки

Документировать «как», игнорируя «почему». Причины решений ценнее пересказа кода.
Писать «для себя». Без учёта читателя текст понятен только автору.
Оставлять устаревшее. Ложная инструкция вреднее пустоты.
Стена текста. Без заголовков и примеров документацию не дочитывают.

Итог

Документация хранит «почему», которого нет в коде.
Приоритет: запуск проекта, неочевидные решения, грабли, контракты.
Пишите под конкретного читателя и его ситуацию.
Обновляйте описание в том же PR, что и поведение, — устаревшее опаснее пустоты.