Планируете ли делать документацию до релиза или после
Что проверяют
Вопрос со встроенной ложной развилкой. Проверяют, видите ли вы, что документация бывает разной и у каждого вида свой момент, и есть ли у вас привычка вести её постоянно, а не героически за вечер до релиза.
Как отвечать
Откажитесь от выбора одного из двух и разложите по видам.
- До кода: контракт API, схема событий, критерии приёмки, запись принятого архитектурного решения. Без них нечего обсуждать на ревью замысла, а после релиза они уже не документация, а археология.
- Из кода: спецификация OpenAPI по контроллерам или минимальным API, XML-комментарии для публичных библиотек. Это часть сборки, отдельного времени не требует и не расходится с реальностью.
- Вместе с изменением: README модуля, заметки к миграции, список изменений. Пишутся тем же пул-реквестом и проходят ревью вместе с кодом.
- После релиза: инструкции дежурному по инцидентам, ответы поддержке. Их честнее писать по факту, иначе получится выдумка о том, как система ломается.
Главный тезис произнесите прямо: «после релиза» на практике означает «никогда», потому что сразу после релиза приходит следующая задача. Поэтому документация входит в определение готовности, а не в отдельный этап плана.
Добавьте признак зрелости: документы лежат в репозитории рядом с кодом и версионируются вместе с ним. Вики в стороне устаревает первой, потому что её никто не видит в диффе.
Где спотыкаются
Выбирают сторону развилки и защищают её. Ответ «всегда заранее» разваливается на первой задаче, где требование поменялось на середине, а «всегда потом» звучит как обещание не писать вовсе.
Второе: обещают вести документацию параллельно разработке и не могут сказать, что именно документируют. Без списка артефактов и места, где они лежат, это лозунг.
Третье: подменяют документацию комментариями в коде. Комментарий, пересказывающий соседнюю строку, не помогает никому, а читателю нужны контракт, ограничения и причина решения.