Документация на данные

Принцип «всё как код» — и таблицы тоже.

Частая проблема в документации — её просто нет ¯\_(ツ)_/¯ а если есть, то она устаревшая.

Так бывает, когда документация не зависит от текущей реальности: красивые описания живут в модном Ноушене, но DDL в Postgres ничего про это не знает))

Что делать? Переселить документацию ближе к реальности. В Яндекс.Такси решили, что все сущности в ДВХ будут описываться в коде — названия, колонки, их тип и комментарии (!). Нельзя просто так поменять атрибут без изменения документации — всё связано.

А раз описания уже в коде, это всё версионируется через гит с указанием ответственных. К тому же всё можно обвешать автотестами (всё как у настоящих разработчиков!): назвал колонку не по канону — не сможешь замержить свой пулл-реквест, пока не исправишь.

А ещё пулл-реквесты удобно ревьюить. Скинул ссылку старшему коллеге и он в одном месте видит все изменения, аккуратно подсвеченные. Если что не так — комментит нужную строку.