Documentation dans les données et l'analyse

La documentation est quelque chose qui est souvent mal compris à l'OMI.
Voici mes réflexions conceptuelles au niveau macro sur le sujet (s'applique aux données et au-delà)

Son Objectif : Contexte & Clarté

Plus précisément, vous voulez vous assurer que les futurs lecteurs/utilisateurs (y compris vous-même !) des modèles/transformations/requête/code/etc comprendront ce qui a été fait sans avoir besoin de revenir vers vous et de vous poser des questions sur le travail que vous avez fait et pourquoi.

C'est des saveurs : plus diversifiées que ce que l'on pourrait croire

Quelques-uns que je considère consciemment:

• Votre code!!! C'est là que tout commence. Le but ultime est la clarté, n'écrivez pas de code ou de modèles intelligents, écrivez quelque chose que tout le monde peut comprendre. Votre code doit se documenter
• Nommage : Il s'agit essentiellement d'un corollaire du 1er point, car votre code a la logique qu'il implémente et le langage/la formulation/la dénomination pour l'exprimer facilement à un lecteur humain. Nommage intuitif utile (pour les fichiers, les jeux de données, les modèles de données, les colonnes…). Des noms comme tmp, tmp_1, test_data, etc… sont définitivement une mauvaise pratique. Si vous les utilisez, assurez-vous qu'ils ne soient jamais exposés au monde extérieur ! Sérieusement…
• Commentaires : Si le code (logique et nommage) ne suffit pas - par exemple pour des cas d'utilisation plus complexes qui nécessitent d'ajouter un contexte historique et de pointer vers une documentation externe -, des commentaires supplémentaires dans le code sont fortement recommandés. Pour éviter de distraire le prochain développeur/lecteur, assurez-vous de le garder concis, clair et certainement pas déroutant. Aucune documentation n'est meilleure qu'une documentation confuse/trompeuse
• ToDos : ToDos est le code, est fondamentalement comme un commentaire++ (un commentaire qui appelle une action future). Utilisez-le stratégiquement par exemple pour gérer intelligemment TechDebt : si vous voyez qu'une refactorisation est nécessaire pour certaines pièces plus anciennes et que vos délais pour le projet en cours ne vous permettent pas de vous y attaquer vous-même, ajoutez définitivement une tâche (avec contexte). Le prochain lecteur y reviendra et décidera quoi faire. C'est ça le développement collaboratif responsable !
• Test : le test aide l'utilisateur/lecteur à comprendre la structure du modèle et les données qu'il traite. Un exemple : les tests d'unicité dans les tests de données aident à comprendre la granularité des données (première chose que je vérifie lors de la lecture des tests dbt .
• Documentation fils dans la base de code (au besoin) : presque tous les langages qui se "respectent" proposent des méthodes conventionnelles pour documenter méthodiquement votre code. Pour dbt, un fichier yml attaché au modèle (sql) que vous construisez est l'endroit où vous pouvez le faire. Python par exemple propose des docstrings . Utilisez-le aussi bien. Cela devrait être utilisé en conjonction avec les commentaires dans le code. Le juste équilibre entre les deux est un art qui se peaufine avec la pratique
• Documentation en dehors de la base de code (comme sur confluence) : principalement pour des sujets contextuels plus complexes, tels que la documentation du cas d'utilisation commerciale d'un modèle ML, le pipeline de rapports, l'architecture, la source de données complexe, etc. Ma recommandation à mon équipe chez The Fabulous est de documenter tout ce qui s'y rapporte au code (logique concrète autour) proche du code, et tout ce qui est plus proche du métier (documentation fonctionnelle) sur confluence

le prochain lecteur sera-t-il confronté à des frictions avec ce que je crée ?'.

Si la réponse est oui, simplifiez davantage et documentez mieux !

Quelques dernières réflexions directrices

• La documentation est un outil : elle doit être considérée comme un outil majeur dans votre flux de travail quotidien, comme votre IDE, traitez-la bien, elle vous fera gagner du temps, à vous et à vos collègues/équipe, plus tard.
• La documentation doit être une habitude : Chez Fabulous, nous appliquons Documentation First pour renforcer cela. Personnellement, je l'ai appris à la dure après être devenu un goulot d'étranglement dans certains projets parce que je n'avais pas fait assez d'efforts dans la documentation fonctionnelle (autour du cas d'utilisation métier, pourquoi et comment je l'ai abordé).
• La documentation est une compétence : une fois que vous aurez commencé à développer l'habitude autour de la documentation, vous commencerez à voir comment vous pouvez l'affiner, l'améliorer, en faciliter la maintenance, en utiliser différents aspects (liste de la section précédente) plus facilement, etc. Personnellement, je commencé à aimer cet aspect une fois que j'y suis arrivé (j'avais l'habitude de détester la documentation avant, comme je détestais les tests…).
• La documentation doit être révisée : comme le code, demandez à quelqu'un de votre équipe de réviser votre documentation. Ceci est par exemple rarement fait pour la documentation en dehors de la base de code. C'est à mon avis l'une des principales raisons pour lesquelles la documentation devient rapidement obsolète (parce qu'elle était mal faite au départ). N'oubliez pas : aucune documentation vaut mieux qu'une documentation trompeuse/confuse
• La documentation est collaborative : Appliquez la règle scout . Comme le code, la documentation peut et doit être améliorée, surtout lorsqu'elle commence à devenir obsolète. J'indique généralement clairement quand une image a été mise à jour, surtout quand je sais que les choses vont changer dans quelques mois. Exemple concret : « Depuis juin 2022, la manière dont nous avons décidé de nous attaquer à ce problème est … à cause de … ».