Привет!
Я работаю 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 '%%' находит все точные и не точные совпадения -
просто поддерживать в актуальном состоянии
Заводим традицию регулярных ревью, закрепляем ответственных и иногда сами проверяем то, что дата последней прожарки/проверки не старше Вашего порога терпимости к свежести контента.
Можем настроить проверки, например - если отчёт меняли и есть закрытая задачка в таск-трекере, а в реестре метрик строки по отчёту не изменились/не появилось новых, то создаём в таск-трекере задачку на изменившего отчёт с просьбой внести документацию и обязательным ревью на лида.
Вот пример кейса, когда документация Вас круто выручит:
На проде решили провести рефакторинг таблицы, на которой в Вашем проекте считали объём заказов.
Из документации Вы быстро-просто получаете ответы на вопросы
- какие объекты затронет рефакторинг - сможете оценить время на эти работы
- какие метрики и в каких отчётах будут показывать некорректную информацию, пока не внесёте изменений - сможете донести до пользователей эту информацию и уберечь от ошибок в принятии решений
Возможно, Вы попробуете использовать мои простые предложения, а может поделитесь своим опытом на эту тему.
Буду рад комментариям!
От документации станет жизнь светлей
и мидлу и даже маленькому джунУ.)
Автор: AkaMikhelson
