Документация нужна не ради документации. Она нужна, чтобы другому человеку можно было передать не только решение, но и причины, ограничения и договорённости вокруг него.
Документировать нужно не всё
Можно обязать команду описывать каждую функцию, создать десятки шаблонов и получить огромную Wiki. Через несколько месяцев текста будет много, доверия к нему — мало.
Я предпочитаю начинать с другого вопроса: какое знание нельзя позволить себе потерять?
Самое ценное в решении — часто не само решение
«Используем PostgreSQL». «Разделили систему на эти сервисы». «Этот модуль нельзя менять независимо».
Через два года важнее знать: почему? Какие варианты рассматривались? Какое ограничение заставило выбрать именно это? Что должно измениться, чтобы решение перестало быть правильным?
Если сохранить только итог, следующий человек либо слепо соблюдает старое решение, либо заново проходит весь путь его автора.
Живая документация встроена в работу
Если документ нужно специально «не забыть обновить», он почти наверняка однажды устареет. Хорошая база знаний связана с реальным процессом принятия и изменения решений.
Решение принято — причина зафиксирована. Изменился контракт между системами — описание меняется вместе с ним. Новый сотрудник не смог разобраться — значит, мы нашли пробел в документации или передаче знаний.
Хороший признак — автора можно не звать
Если после чтения документа всё равно нужно пригласить автора на встречу, значит, документ не передал весь нужный контекст.
Один из моих любимых критериев: может ли другой компетентный человек принять следующее решение, не восстанавливая весь контекст с нуля?
Что я обычно проверяю
- Какие решения невозможно понять без их авторов.
- Какая документация реально используется при следующем изменении.
- Где зафиксированы причины и ограничения, а не только итог.
- Где новые сотрудники теряют контекст при входе в проект.
- Какие регулярные устные объяснения можно заменить понятной документацией.