Документация

Ваша работа — так же страстно защищать код.

Роберт Мартин — «Чистый код»

Карта документации связывает обучение, задачи, справочник и объяснение решений. — Communication Engineering · документация

Документация — интерфейс к системе и памяти команды. Плохая документация увеличивает зависимость от конкретных людей, заставляет повторять ошибки и превращает онбординг в археологию.

Проблема редко решается призывом «документировать больше». Документов становится больше, а найти ответ сложнее. Нужна информационная архитектура и жизненный цикл.

Четыре функции

Документы удобно разделять по задаче читателя:

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

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

Минимальная карта системы

Для продукта полезны:

обзор: что это, для кого и где границы;
быстрый старт с проверяемым результатом;
локальная разработка и тесты;
архитектура и основные потоки;
контракты и справочники;
эксплуатация, наблюдаемость и восстановление;
решения и известные ограничения;
владелец и канал обновления.

Не каждая система требует отдельный портал. Малому проекту достаточно хорошего README и нескольких ADR. Масштаб документации должен следовать стоимости восстановления знаний.

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

Устаревание уменьшается, когда документ обновляется в том же процессе, что и система:

PR меняет API — обновляет reference;
миграция меняет операцию — обновляет runbook;
новое решение — создаёт ADR;
инцидент выявляет пробел — добавляет проверку и инструкцию.

Фраза «потом задокументируем» обычно означает, что контекст исчезнет раньше.

Проверка документации

Лучший тест — задача пользователя. Дайте человеку без локального контекста выполнить шаг и наблюдайте, где он:

не понимает термин;
выбирает неверный путь;
копирует команду, не понимая результат;
не знает, как проверить успех;
обращается к автору.

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

Проблема

README содержит 40 команд без объяснения. Новичок запускает опасный скрипт против общей среды.

Изменение

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

Результат

Документ не только передаёт знание, но и проектирует безопасное поведение.

Документация и код

Читаемый код снижает потребность объяснять детали реализации, но не хранит бизнес-причины, отвергнутые альтернативы и операционные договорённости. Тест может показать контракт, но не объяснить, почему он именно такой.

Не выбирайте между «самодокументируемым кодом» и текстом. Размещайте знание в форме, которая лучше всего сохраняет его функцию.

Антипаттерны

wiki-свалка без навигации;
копия одного текста в нескольких местах;
инструкция без проверки результата;
диаграмма без даты и владельца;
документация как наказание после проекта;
критичное знание только в видео;
автоматическая генерация, выдаваемая за объяснение.

Тест одной задачи

Выбери частый вопрос команды и попроси человека найти ответ без подсказки. Измерь путь: поиск, открытые страницы, ошибки и финальный результат. Исправь не только текст, но и навигацию.