Я перепробовал несколько способов вести документацию по базе данных — и у каждого были свои проблемы: информации недостаточно, сложно поддерживать, непонятна команде. Хуже всего, что плохая документация по БД тянет за собой проблемы с требованиями к данным — а это не только таблицы, но и миграции, и данные в коде. В какой-то момент я понял, что пытался решить одним документом три разные задачи.

Пользовательское требование описывает, что нужно пользователю. Критерии приёмки — фиксируют, как это проверить. Но между «что нужно» и задачей в Jira — пропасть. Чтобы её закрыть, я пишу функциональные требования — с use case'ами, из которых тестировщик может собрать тест-кейсы, а разработчик — понять ожидаемое поведение системы.

Когда документация переехала в вики, люди решили, что страницы бесплатные, и начали писать всё в одном документе. Платить в этом случае всё равно приходится, но только не деньгами, а временем и нервами исполнителей, которые эту документацию читают. Я покажу, как разбиваю это на систему связанных страниц, где у каждой — своя роль, а точка входа — одна.