Какую документацию поддерживать в команде и как не дать ей устареть?
- Зачем разработчику писать документацию?
Минимум, который окупается: README с запуском проекта, схема архитектуры и потоков данных, инструкции для дежурного (runbook: что делать при типовых сбоях), решения (ADR) с причинами, описание API. Документация живёт рядом с кодом (в репозитории) и обновляется в том же PR, что и код. Устаревшее хуже отсутствующего — его удаляют. То, что можно сгенерировать (схема API из кода), генерируют.
- Проверка: новый человек запускает проект только по README
- Пункт «обновлена документация» в шаблоне PR
- Короткие страницы под конкретные вопросы лучше одного огромного документа
А ещё Ответили на вопрос в чате второй раз — пора записать
Подробно
Что не стоит документировать: то, что очевидно из кода и названий; подробные описания, которые никто не будет обновлять.
Runbook — пример: «Алерт: очередь писем растёт. Проверить: дашборд X, логи сервиса Y. Частая причина — лимит SMTP-провайдера. Действие: переключить на резервного провайдера флагом Z».
Что хотят услышать
- Что документировать: запуск, архитектура, runbook, решения.
- Рядом с кодом и в том же PR.
- Удалять устаревшее.
Проверьте себя
Один верный вариант. Подумайте, потом откройте ответ.
Показать варианты и ответ
- ✗Документировать каждую функцию длинными комментариями, даже очевидные
- ✓README, архитектура, runbook и решения — рядом с кодом, обновляются в том же PR
- ✗Хранить всю документацию в отдельной вики, подальше от кода, и обновлять её раз в год
- ✗Документация не нужна, если код хороший
Разбор темы
- Рост коллег — наставничество, онбординг, ревью и общие знания
Как помогать расти младшим коллегам, вводить новичка в работу, учить через код-ревью, поддерживать документацию и не быть единственным экспертом.
Связанные вопросы
Разбор собеседования с sotto
После собеседования sotto разбирает разговор: оценка, каждый вопрос — хорошо, частично или слабо, чего не хватило в ответе и над чем поработать к следующему разу. Первые 30 минут бесплатно.