Качества документации: непротиворечивость

Продолжим говорить о качествах документации. До этого мы рассмотрели краткость и полноту, сегодня поговорим о непротиворечивости.

ТЗ и Соглашения не должны противоречить ни другим требованиям внутри проекта, ни самим себе. Если в начале документа мы говорим "сделай так", а в конце "сделай эдак", или в одном документе указываем что поле содержит данные Х (например, дату возврата товара), а в другом это же поле содержит данные У (н-р, дату возврата денег клиенту) — ничего хорошего от данных мы в итоге не получим.

Ещё один простой пример: в ТЗ указано время обновления витрины раз в сутки, в jira требование — "обновление раз в 15 минут", какой результат ожидать от инженера? Будет круто, если он придёт за уточнением, но это бывает не всегда. Плюс время потраченное на разбирательства явно можно использовать более эффективно.

Второй пример, в компании "Рога и копыта" было решено все даты в хранилище хранить в UTC, это было зафиксировано в соглашении "Обработка часовых поясов". По прошествии лет, после некоторой ротации сотрудников об этом регламенте было забыто. И новый аналитик реализует загрузку данных в хранилище в местном времени, затем на основе старых и новых данных строятся аналитические отчёты. О каком качестве полученной информации мы можем говорить?

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

Что делать? Ревью, ревью и ещё раз ревью. Как самостоятельные, так и проводимые другими аналитиками.

Второй момент — поддержание документации (как минимум основных соглашений) в актуальном и консистентном состоянии. Да, это требует усилий, времени и внимания, но они окупятся в будущем.

Важно подчеркнуть, что даже наличие качественной документации не гарантирует отсутствия тех или иных ошибок. Если документация слишком объемная, сложная для понимания или спрятана в недрах проекта так, что о ней никто не знает, то толку от неё будет мало 🥂

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