Documentation technique utile

La plupart de la documentation technique est un cimetière de wikis obsolètes que personne ne lit. La documentation n’est utile que si elle est facile à trouver, rapide à lire et fiable. Pour y arriver, il faut changer d’approche : arrêter d’écrire des romans et privilégier des formats courts, actionnables et, surtout, qui vivent au plus près du code. Une bonne documentation n’est pas un rapport, c’est un ensemble d’exemples, de contrats et d’historiques de changements.

prérequis

• Repo commun: Le code et la documentation vivent au même endroit (ex: un repo Git).
• Convention de nommage: Des noms clairs et prévisibles pour les datasets et les colonnes.
• Processus de relecture: Une culture où la relecture de la documentation est aussi normale que la relecture du code.

idées clefs

La documentation utile repose sur des principes simples, conçus pour et par des développeurs.

pas à pas

étape 1: la fiche minimale

Pour chaque jeu de données critique, créez un fichier README.md à la racine de son répertoire. Il doit répondre aux questions essentielles en moins de 30 secondes de lecture.

• quoi: une phrase simple décrivant le dataset.
• pour qui: les équipes ou les cas d’usage principaux.
• colonnes utiles: la liste des 3 à 5 colonnes les plus importantes, avec une description simple.
• exemples: une requête sql prête à copier pour un cas d’usage courant.
• limites: ce que le dataset n’est pas (ex: “ne contient pas les données de moins d’une heure”).
• contact: le nom de l’équipe propriétaire ou un canal slack.

étape 2: les liens vivants

La documentation doit pointer vers la source de vérité : le code. Intégrez des liens directs vers les fichiers importants. Cela garantit que la documentation ne diverge pas du code.

• source du code: [models/ventes/orders_v.sql]
• tests de qualité: [tests/ventes/orders_v.yml]
• dashboard principal

étape 3: la revue éclair

Chaque modification de la documentation doit passer par une pull request, comme le code. La revue doit être rapide et efficace.

pièges frequents

• Symptôme: Personne ne contribue au wiki de l’entreprise.

  • Cause: La documentation est loin du travail quotidien des développeurs.
  • Correctif: Mettre la documentation dans le repo Git. La modifier doit faire partie du processus de développement normal.

• Symptôme: Les utilisateurs disent “je ne sais pas comment utiliser cette table”.

  • Cause: La documentation est une longue prose sans exemples concrets.
  • Correctif: La section la plus importante de votre documentation est le snippet de code prêt à copier. C’est la première chose que les gens cherchent.

• Symptôme: Un changement sur une table casse des dashboards sans que personne ne comprenne pourquoi.

  • Cause: Les versions et les changements ne sont pas tracés.
  • Correctif: Rendre le CHANGELOG.md obligatoire. Chaque pull request qui modifie la structure ou la logique d’un dataset doit ajouter une ligne à ce fichier.

faq

• Qui doit écrire la documentation ? La personne qui écrit le code. La documentation n’est pas une tâche à part, c’est une partie intégrante de la livraison d’un produit de données. Le processus de revue par les pairs garantit sa qualité et sa clarté.

• Comment s’assurer que la documentation reste à jour ? En la gardant courte et proche du code. Une fiche de 10 lignes avec des liens vers le code a beaucoup plus de chances de rester à jour qu’un document de 20 pages. L’automatisation peut aussi aider, en générant une partie de la documentation (comme le schéma des colonnes) directement depuis la base de données.