Notes sur le côté humain de la documentation dbt : inadéquation des audiences, patterns de rédaction des descriptions, et qualité de la documentation comme infrastructure pour les outils d’IA. Pour générer de la documentation (scaffolding, outils d’IA, RAG), voir le hub de documentation dbt propulsée par l’IA. Pour maintenir la précision de la documentation dans le temps, voir le hub de fraîcheur de la documentation.
Ordre de lecture
-
Inadéquation des audiences de la documentation dbt — Pourquoi la documentation dbt n’est pas lue : les équipes écrivent pour les ingénieurs, pas pour les analystes et les utilisateurs métier. Couvre les problèmes d’interface, de portée et de maintenance.
-
dbt Model Description Writing Patterns — Un framework en trois questions pour les descriptions de modèles (système source, grain, exclusions), les patterns de description de colonnes (unités, fuseaux horaires, relations), les descriptions de sources, et quand utiliser
descriptionvsmeta. -
La qualité de la documentation détermine l’utilité de l’IA — La qualité de la documentation détermine directement l’utilité des outils d’IA. Couvre l’échec du chatbot Roche, la boucle de rétroaction bidirectionnelle documentation-IA, et les résultats des équipes qui ont investi dans l’application.
Mécanismes de diffusion
Une fois que vous avez de bonnes descriptions, les diffuser aux bonnes personnes est tout aussi important que le contenu :
- dbt Persist Docs pour les commentaires d’entrepôt — Pousser les descriptions là où les analystes travaillent déjà (panneau de schéma BigQuery, commentaires de colonnes Snowflake, navigateurs de schéma des outils BI). Souvent la correction avec le meilleur rapport effort/impact pour l’adoption.
- Syntaxe et réutilisation des blocs doc dbt — Écrire les descriptions une fois, les référencer partout. Particulièrement utile combiné à persist_docs pour des descriptions cohérentes dans les modèles et les commentaires d’entrepôt.
- Options de personnalisation du site dbt Docs — Le bloc doc
__overview__, les couleurs des nœuds du DAG, et le masquage des modèles intermédiaires. De petits changements qui rendent le site docs par défaut plus navigable pour les utilisateurs non techniques. - Alternatives à dbt Docs par défaut — Quand le frontend par défaut ne suffit pas : le remplacement Next.js de Dagster, les catalogues de données, dbt Cloud Catalog.