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