Главная идея: документация должна вести читателя от смысла к деталям. Сначала объясняется, зачем существует модуль и какую задачу он решает. Потом показывается логика работы. Только после этого можно переходить к структурам, интерфейсам, таблицам, API и другим деталям реализации.
Не начинай описание с кода.
Плохой старт:
Модуль резолвит ACL через набор ролей и permission entries.
Хороший старт:
Модуль управления доступом определяет, имеет ли пользователь право выполнить действие над объектом. Перед выполнением защищенной операции система спрашивает этот модуль, можно ли продолжать.
Читатель сначала должен понять назначение, а не внутренние названия сущностей.
Этот уровень должен быть понятен любому читателю.
Ответь на вопросы:
На этом уровне не нужно описывать структуры, интерфейсы, SQL-таблицы и внутренние функции.
Здесь нужно рассказывать не про файлы и классы, а про процесс.
Пиши как историю:
Такое описание легче читать, потому что оно совпадает с тем, как человек мысленно представляет работу системы.
После описания процесса можно переходить к архитектуре.
Здесь уместно перечислить компоненты и зоны ответственности:
Важно объяснять не просто "что есть", а "за что отвечает каждая часть".
Только на этом уровне стоит описывать:
Этот раздел нужен в первую очередь разработчику, который будет менять код. Остальные читатели должны иметь возможность остановиться раньше и все равно понять суть.
Каждую страницу модуля пиши по одному шаблону.
# Название модуля
## Назначение
Зачем существует этот модуль и какую задачу он решает.
## Когда используется
В каких сценариях система обращается к модулю.
## Как работает
Пошаговое описание основного процесса без привязки к конкретным функциям.
## Компоненты
Из каких частей состоит модуль и за что отвечает каждая часть.
## Пример
Один реальный сценарий от начала до конца.
## Ограничения
Что модуль не делает, какие случаи не покрывает и какие решения были сознательно не выбраны.
## Детали реализации
Интерфейсы, структуры, таблицы, API, ошибки и другие технические подробности.
Не пытайся сразу "объяснить алгоритм". Сначала ответь на четыре вопроса.
Какие входные данные получает система.
Пример:
Какие шаги выполняет система.
Пример:
Какой результат возвращается.
Пример:
Опиши поведение при ошибках и пограничных случаях.
Пример:
Почти любой технический текст становится понятнее, если в нем есть пример.
Плохо:
Проверяется разрешение на выполнение действия.
Хорошо:
Пользователь Иван пытается удалить файл
report.pdf. Система определяет, что Иван имеет рольeditor. Для этой роли разрешено удаление файлов. Поэтому операция продолжается.
Пример должен быть простым и конкретным. Не нужно пытаться покрыть все случаи сразу.
Используй диаграммы не для красоты, а чтобы ответить на конкретный вопрос читателя.
Отвечает на вопрос: "Из чего состоит система?"
Используется в начале документации крупного модуля.
Пример:
. VFS
|
------+------
| | |
Mount Driver Cache
Отвечает на вопрос: "Какие шаги выполняются?"
Используется для алгоритмов:
Пример:
Получить путь
|
v
Нормализовать путь
|
v
Найти mount
|
v
Mount найден?
| |
нет да
| |
ошибка Передать driver
Отвечает на вопрос: "Кто с кем взаимодействует?"
Используется, когда важно показать обмен вызовами между компонентами.
Пример:
Client -> HTTP handler -> VFS -> ACL -> Driver -> Filesystem
Если описываешь алгоритм, чаще всего нужна блок-схема. Если описываешь взаимодействие модулей, чаще всего нужна sequence diagram.
Для крупных подсистем вроде VFS или ACL лучше не складывать все в одну страницу.
Пример дерева страниц:
docs/
vfs/
overview.md
architecture.md
components.md
algorithms.md
scenarios.md
api.md
errors.md
acl/
overview.md
architecture.md
permissions.md
algorithms.md
scenarios.md
errors.md
Стартовая страница может быть красивой навигацией с карточками, например в Wiki.js, но она не заменяет содержание. Сначала нужно продумать дерево страниц, потом делать витрину.
Если нужно объяснить не только устройство системы, но и причину решения, используй ADR.
ADR отвечает на вопрос: "Почему мы сделали именно так?"
Шаблон:
# ADR-001: Название решения
## Контекст
Какая ситуация была в проекте.
## Проблема
Что нужно было решить.
## Варианты
Какие варианты рассматривались.
## Решение
Какой вариант выбран.
## Последствия
Что это решение упростило, усложнило или ограничило.
ADR особенно полезны для решений вроде:
Перед тем как считать страницу готовой, проверь:
Хорошая документация отвечает на вопросы в таком порядке:
Если придерживаться этого порядка, документация будет понятна и человеку вне проекта, и разработчику, который пришел менять реализацию.