Как держать документацию актуальной
Вопрос
Как организовать документацию требований, чтобы она не устаревала?
Попробуйте сами
Ответьте вслух за 2 минуты, как на собесе. Потом сверьтесь с тезисами: что прозвучало, а что нет.
Показать ответ и разбор
Коротко
Что должно прозвучать в ответе
Одно место для актуальной версии, ссылки вместо копий
Документация как часть Definition of Done
Docs as code: OpenAPI и диаграммы рядом с кодом, ревью
Версии и история изменений, пометка устаревшего
Документировать решения и причины, а не всё подряд
Что могут спросить следом
- Что делать с документацией, которая уже устарела?
- Кто отвечает за актуальность?
Разбор
Главное правило: у каждого факта одно место, остальные на него ссылаются. Контракты API и событий храню в репозитории в OpenAPI и AsyncAPI, диаграммы в PlantUML рядом, изменения проходят ревью вместе с кодом, и документация не может отстать от реализации. Обновление требований входит в Definition of Done задачи. У страниц спецификаций есть история изменений и владелец. Записываю не только что решили, но и почему: через год это важнее деталей. Устаревшее не удаляю молча, а помечаю и даю ссылку на актуальное.
Ответьте сами, а не прочитайте
В тренажёре вопрос попадёт в повторения и вернётся, когда начнёт забываться. Плюс билеты с зачётом: 20 вопросов, не больше 2 ошибок.