Привет!

Я работаю Chief Data Officer в средней российской компании и, думаю, попробовал «всякое» в плане работы с документацией для команды, которая работает с данными.
Хочу поделиться своим опытом того, что «маст хев» в документации в Вашем проекте, когда есть планы вроде «make analysis great [again]».

Если работаете с цифрами, наверняка Вы уже не раз задавались простыми вопросами вроде

• как это считается?

• откуда берётся?

• что значить эта аббревиатура?

• а кто это вообще просил?

• кто сопровождает этот отчёт?

• что эта колонка в таблице означает?

• что хотели решить этим дешем?

и вопросами чуть посложнее

• в каких отчётах мы считаем эту меру?

• вот если табличка не обновилась, какие отчёты от неё зависят и сейчас не обновлены?

• а мы всегда считали именно так эту меру?

Вот быстрые и правильные ответы на эти и многие другие вопросы - это задача хорошей системы документации. Поэтому многие хотят иметь понятную, доступную и актуальную документацию. И многие не имеют. Потому что хотя бы начать записывать свой опыт - уже подвиг, а записывать так, чтобы удобно было искать, читать и поддерживать в актуальном состоянии эту информацию - задачка с тремя ***.

Если в Вашей голове уже промелькнули слова вроде Confluence и DataCatalog, то коротко про нюансы.

Confluence работает плохо без дополнительного сервиса, который индексирует контент confluence, в остальном, ничего против не имею. DataCatalog-системы - это то, что больше полезно разработке и, возможно, инженерам данных, в меньшей степени - аналитикам и пользователям отчётов.

Здесь не будет про крутые продукты и автоматизации.

Да и не верю я в то, что хорошую документацию можно «генерить LLM/AI» или автоматически получать откуда‑либо.

Хорошая документация — это результат удобного процесса работы команды профессионалов и автоматизации проверок — страховки от «человеческого фактора».

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

Я за варианты реализации документации, которая позволит малой кровью обеспечить себя — лида, data‑команду, руководителя и заказчиков оптимальным набором полезной информации описывающей результаты трудов команды на плоских таблицах.

Важно: критерии качества для документации, которые я предлагаю ценить в первую очередь

• просто дополнять

• просто находить нужное

• просто поддерживать в актуальном состоянии

Сразу к делу, список

Реестр поделок

Именно поделок, потому что труд команды, которая работает с данными, генерит много разного и полезного. Как то: отчёты, даги/пакеты ETL, скрипты для автоматизаций и рассылок SQL/Py/JS и пр.

Зачем это надо?

• Навигировать обращения по поделкам к тем, кто поделки сопровождает.
  Больше не нужно искать по чатам или таск-трекеру концы и ответственных. Экономите нервы и минуты всем участникам процесса.

• Поддерживать поделки в актуальном состоянии.
  
  В работе с данными контент может стать не актуальным уже спустя 1-2 месяца. Заведите полезную церемонию - раз, например, в 2 месяца проводить ревью наработок с командой. Не обязательно всю команду тащить, 1-3 специалиста отлично "прожарят" поделки команды. О самом процессе прожарки хочу написать отдельно. Взял в работу этот приём из интервью с Романом Буниным.
  
  Роман, если ты читаешь, благодарю за твою мудрость!

• Иметь под рукой нужные метаданные вроде заказчика поделки, расположения, связи с таск-трекером, актуальности контента.
  
  Иногда нужно вспомнить - для кого делали эту поделку, где она лежит, как и где её описывали, чтобы восстановить ход событий и принять очередное важное решение по развитию поделки.
  

• Автоматизировать возможные проверки качества и состояния поделок на метаданных.
  Возможно Вам мало просто иметь сделанные поделки и Вы хотели бы узнавать о проблемах в обновлении или наполнении очередного отчёта не от разгневанного пользователя

Вариант реализации в плоской таблице

Предполагаю, что здесь и далее наполнение интуитивно-понятно из названия поля. Если нет, пожалуйста, уточните.

Реестр метрик

Метрика <> поделка. Метрики - это всё, что вы когда-либо считали. Это не дерево метрик, дерево предполагает построение графов.

Зачем это надо?

• Иметь эталон расчёта по каждому вычислению и перепроверять свои же наработки.
  Бывает так, что похожий расчёт делает несколько участников команды или один, но очень растянуто по времени. Полезно сравнить расчёты с тем, как это было задумано. Да и погрузить коллегу в особенности расчёта будет проще

• Восстанавливать историю изменений вариантов расчётов.
  Возможно, в Вашем проекте классический "оборот" считался в течение прошлого года по одной формуле, а в этом году что-то поменялось в бизнесе или аналитик "прозрел" и учёл то, что не учёл раньше. Поменялся расчёт в этом году. И начальник просит сравнить год с годом. Может потребоваться и расчёт по-старому, и по-новому.

• Поддерживать понимание пользователем.
  Один из ключевых драйверов развития data-культуры Вашего проекта - это доверие к цифрам. Формула доверия = Понимание расчёта * Кол-во успешных проверок цифр.

Вариант реализации в плоской таблице

Почему такую табличку не заменить репозиторием в условном git? Трудно научить заказчика в git лазить. Да и надо ли?

Про качество.

• Просто дополнять.
  Как и в случае с реестром поделок, на ревью проверяем что в реестр метрику внесли.

• Просто находить нужное.
  Всё то же: ctrl + f или like '%%' находит все точные и не точные совпадения.

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

Глоссарий

Это сердце Вашей документации.

Здесь указываем всё: описание поделок, метрик, аббревиатуры, людей, контакты которых важно не забыть, описание конкретных баз/таблиц/колонок, связей между ними, связей с отчётами и прочее.

Зачем это надо?

• через простой поиск вы шарите все накопленные знания с командой и прочими страждущими
  Для меня идеал доки - это когда можно ввести в поиск то, что нужно и, если есть хоть какое-то упоминание, получить ответ по этим упоминаниям. Не в 10 местах разных ввести в поиск, а в одном и ответ получить в удобном, понятном формате

• определить связи и зависимости между контентом
  Data-lineage, бизнес-проверки, pipeline обновления отчётов - это главные клиенты связей и зависимостей. Да, модный и современный DBT может собирать связи "из коробки", но форма для поиска по этим связям Вам всё-равно пригодится.)

• описать аббревиатуры и сокращения
  Новичкам и не новичкам может быть полезно

• говорить со всеми на одном языке - свести к одному формату разные варианты написания одного и того же
  И убрать двусмысленности из диалогов. Если что-то называем выручкой, давайте одинаково понимать что это такое. Если Маркетинг хочет иметь свой вариант выручки, назовём это "Выручка_vМаркетинг")

Вариант реализации в плоской таблице

Немного пояснений про качество

• просто дополнять
  Прописываем процесс работы каждой роли в команде, указываем на каких этапах нужно заполнять. На ревью проверяем что в таблицы записи добавили

• просто находить нужное
  Плоская таблица = ctrl + f или like '%%' находит все точные и не точные совпадения

• просто поддерживать в актуальном состоянии
  Заводим традицию регулярных ревью, закрепляем ответственных и иногда сами проверяем то, что дата последней прожарки/проверки не старше Вашего порога терпимости к свежести контента.
  Можем настроить проверки, например - если отчёт меняли и есть закрытая задачка в таск-трекере, а в реестре метрик строки по отчёту не изменились/не появилось новых, то создаём в таск-трекере задачку на изменившего отчёт с просьбой внести документацию и обязательным ревью на лида.

Вот пример кейса, когда документация Вас круто выручит:

На проде решили провести рефакторинг таблицы, на которой в Вашем проекте считали объём заказов.

Из документации Вы быстро-просто получаете ответы на вопросы

• какие объекты затронет рефакторинг - сможете оценить время на эти работы

• какие метрики и в каких отчётах будут показывать некорректную информацию, пока не внесёте изменений - сможете донести до пользователей эту информацию и уберечь от ошибок в принятии решений.

Возможно, Вы попробуете использовать мои простые предложения, а может поделитесь своим опытом на эту тему.

Буду рад комментариям!

От документации станет жизнь светлей
и мидлу и даже маленькому джунУ :-)