tgoop.com/big_data_systems_analysis/68
Last Update:
Качества документации: непротиворечивость
Продолжим говорить о качествах документации. До этого мы рассмотрели краткость и полноту, сегодня поговорим о непротиворечивости.
ТЗ и Соглашения не должны противоречить ни другим требованиям внутри проекта, ни самим себе. Если в начале документа мы говорим "сделай так", а в конце "сделай эдак", или в одном документе указываем что поле содержит данные Х (например, дату возврата товара), а в другом это же поле содержит данные У (н-р, дату возврата денег клиенту) — ничего хорошего от данных мы в итоге не получим.
Ещё один простой пример: в ТЗ указано время обновления витрины раз в сутки, в jira требование — "обновление раз в 15 минут", какой результат ожидать от инженера? Будет круто, если он придёт за уточнением, но это бывает не всегда. Плюс время потраченное на разбирательства явно можно использовать более эффективно.
Второй пример, в компании "Рога и копыта" было решено все даты в хранилище хранить в UTC, это было зафиксировано в соглашении "Обработка часовых поясов". По прошествии лет, после некоторой ротации сотрудников об этом регламенте было забыто. И новый аналитик реализует загрузку данных в хранилище в местном времени, затем на основе старых и новых данных строятся аналитические отчёты. О каком качестве полученной информации мы можем говорить?
Конечно, проект — живой организм и в реальности часто получается так, что соглашения изменились, но исправились только в одном месте (или вообще нет), затем пришёл новый сотрудник, который не смог разобраться где правда, и решил мести новой метлой. Но в будущем такой подход приведёт к потере доверия к данным, что в свою очередь сделает хранилище малопригодным для принятия важных бизнес-решений.
Что делать? Ревью, ревью и ещё раз ревью. Как самостоятельные, так и проводимые другими аналитиками.
Второй момент — поддержание документации (как минимум основных соглашений) в актуальном и консистентном состоянии. Да, это требует усилий, времени и внимания, но они окупятся в будущем.
Важно подчеркнуть, что даже наличие качественной документации не гарантирует отсутствия тех или иных ошибок. Если документация слишком объемная, сложная для понимания или спрятана в недрах проекта так, что о ней никто не знает, то толку от неё будет мало
#документация