Документация данных

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

Описание производим на естественном языке с разметкой в Markdown.

Зачем нужна документация?

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

На какие вопросы отвечает документация?

Документация должна дать ясные ответы на три вопроса:

• Как появляются данные? — это происхождение данных.
• Что данные из себя представляют? — это смысл данных.
• Зачем нужны эти данные? — это назначение данных.

Происхождение данных

Это не только lineage, нам мало понимать, что является источником, нам нужно понимать сам источник. Если существует подробное описание сервиса, являющего источником данных, скопировать его, адаптировав под нашу документацию, будет хорошей идеей. Это даст нам более полное понимание бизнес-процессов компании.

Смысл данных

Данные — это не только их физическое представление, зафиксированное в контрактах, но и семантика. У каждого поля есть свой смысл, совокупность полей обретает больше смысла, а связи между различными данными привносят ещё больше смысла. В контрактах существует description как для самого контракта, так и для полей в нём, но этого не всегда достаточно.

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

Примеры:

• Допустим, среди полей есть некий идентификатор статуса, а сама статусная модель не отражена ни в каких справочниках, следовательно это не будет зафиксировано в refs. Фактически он будет представлять из enum, набор значений которого следует описать в документации.
• Допустим, среди полей есть некий barcode. Так или иначе, он имеет некий формат, следует сослаться на его описание во внутренней документации компании или, например, в стандарте ISO.
• Допустим, есть поле, являющееся сложным составным идентификатором кастомного формата. Опишите этот формат.

Старайтесь не противоречить description, а дополнять его. Если в процессе описания вы понимаете, что description некорректен, следует его исправить. Но старайтесь ограничить количество изменений, так как любые изменения контракта приводят к порождению новой версии

Назначение данных

Данные нужны не только для аналитики, более того, это их второстепенное назначение. Данные порождаются какими-то бизнес-процессом, существующим в компании, они необходимы его для поддержания. Опишите этот бизнес-процесс на доступном вам уровне понимая, используя любые доступные вам инструменты, включая ссылки на внешние источники, но не ограничиваясь ими.

Что ещё следует описать?

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

Каковы требования к документации?

Придерживайтесь энциклопедического стиля, избегайте вольностей, ориентируйтесь на Википедию в качестве эталона.