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

Документация, совпадающая с реальностью

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

Что входит в категорию

Документы, у которых есть работа

Каждый существует, чтобы ответить на вопрос, который кто-то действительно задаст.

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

Контекст, контейнеры и компоненты — каждый уровень выведен из кода и прослеживается обратно к нему.

Записи архитектурных решений

Почему система именно такая: решение, альтернативы и цена. Тот документ, который экономит следующему человеку месяц.

Диаграммы последовательностей

Важные сценарии, нарисованные так, как они реально выполняются, включая ветки ошибок, которые обычно забывают.

Регламенты выкладки

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

Реестр интерфейсов

Все API и точки интеграции, что они обещают, кто от них зависит и что сломается при изменении.

Эксплуатационная документация

Где что работает, что проверять при странном поведении и какие сигналы что-то значат.

Как идёт работа над документацией

  1. Собирается по системе, а не по памяти

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

  2. У каждого утверждения есть источник

    Элемент схемы, который нельзя привязать к файлу, — это рисунок, а не документация.

  3. Пробелы называются, а не заполняются

    Там, где система действительно неясна, документ так и говорит. Это полезнее уверенной догадки и безопаснее для решений.

  4. Можно отдать человеку

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

Когда вкладываться в документацию

Может подождать, если

Продукта через три месяца может не быть

Один человек и строит, и эксплуатирует всё

Архитектура ещё меняется каждую неделю

Пора сейчас, если

Вы вводите в проект разработчиков или подрядчика

Клиент или инвестор проводит проверку

Единственный человек, который это понимал, уходит

Вы собираетесь пустить сюда ИИ-агента

Выберите категорию под своё беспокойство

Опишите ситуацию своими словами и посмотрите процедуру — и её стоимость — до того, как что-то потратите.