Documentation As Code

L'usage des Wikis au sein des projets¶

En travaillant sur un projet, vous aurez tôt ou tard à affronter le problème de la documentation. Soit elle n'est pas à jour, soit manquante, souvent perdue dans les limbes d'un répertoire partagé ou d'une GED/Sharepoint.

Avec l'essor de l'agilité, une dérive fréquente a été l'inconsistance de la documentation lorsque celle-ci n'est pas maintenue au fil de l'eau. Si les tests étaient le sacrifié sur le totem de la production alors la qualité de la documentation n'imaginez même pas. Entre une spécification fournie par une MOA et une implémentation qui colle avec la réalité du terrain, vous venez de dériver la connaissance de vos business owners.

Pendant des années, j'étais grand fan de la solution Confluence pour son approche Wiki. Diffuser la connaissance est une nécessité pour tendre vers la standardisation et augmenter le niveau de connaissance des collaborateurs.

Mais à grande échelle, les Wikis montrent des limites :

• la recherche devient complexe,
• la responsabilité est diluée,
• les informations se dupliquent,
• les workflows diffèrent selon les personas (développeurs, métiers, fonctionnels),
• la publication en version reste souvent manuelle ou sous-optimale.

Par expérience, je considère qu'une page non mise à jour depuis plusieurs mois est souvent déjà obsolète. Une documentation sur un produit rédigée par une équipe distante des responsables du produit est souvent moins pertinente.

En développant des utilitaires, pour gagner en engagement, la documentation est indispensable. Rapidement, l'évidence est de basculer sur la Documentation as Code pour simplifier son propre flux de travail. Il est plus simple de consulter la documentation dans le dépôt git pour retrouver la bonne info pour mes developpeurs que de parcourir du code. Il arrive même qu'un développeur vous réalise une pull request pour corriger une info.

Pourquoi Docs As Code ?¶

Docs As Code est une approche qui traite la documentation comme du code :

• contenu stocké en texte brut dans un dépôt Git,
• versionné avec les mêmes règles que le code source,
• soumis à revue via merge requests / pull requests,
• publié automatiquement par des pipelines CI/CD.

L'essor de l'IA générative¶

La documentation a porté d'ia agentique devrait plier l'argumentation. En rapprochant la doc du code vous allez vous mettre en capacité de donner du contexte pertinent à votre agent. Définissez des conventions d'arborescence et avec les bonnes règles d'instruction, vos requêtes devraient être optimisés en nombre de token.

Si vous n'êtes pas du genre locace ou un peu trop enjouée, l'IA restructura votre propos avec une touche professionnelle.

Vous pourriez faire la même chose avec un mcp dédié a votre wiki (s'il en existe un). L'avantage c'est que vous n'aurez pas a le configurer et vous limiterez le nombre de requêtes nécessaire à son fonctionnement.

Ce que cela change¶

On le devinait par l'approche As Code mais concrètement on se donne les moyens d'améliorer son produit par design.

Des frameworks, utilitaires existent dans la mise en oeuvre. Parfois, vous n'êtes qu'à 3 commits de passer du brouillon à l'état de l'art.

Quelle solution adaptée ?¶

Le choix d'une solution est multi-factorielle.

• Quels sont mes compétences à disposition dans l'équipe ?
• quels sont les fonctionnalités obligatoires (recherche, navigation, docstring, ...) ?
• Est-ce que je pars déjà d'un existant ?
• Quels types d'informations ai-je besoin de mettre en forme (swagger, notes d'architecture, guides) ?

Solutions courantes Static Site Generator (SSG)¶

Lorsque vous démarrez de nul part, il faut rester modeste pour obtenir des gains immédiats. Une solution qui met en forme des fichiers Markdown peut largement suffire avant d'explorer des alternatives. Votre README.md aura des compagnons de route et il sera plus facile d'accompagner un collectif.

Personnellement, j'ai commencé par MkDocs (vanilla) puis Material for MkDocs et Zensical : en quelques heures vous avez un site statique opérationnel avec des fonctionnalités avancées. Le faible investissement permet d'itérer rapidement.

Voici un tableau comparatif des solutions de Static Site Generator les plus courantes :

Outils complémentaires¶

Pour parfaire votre pipeline, vous pouvez considérer les utilitaires :

Fonctionnement¶

Structure¶

Dans votre dépôt git, la convention est de créer un répertoire docs à la racine.

Processus¶

Le nouveau processus de rédaction de la documentation est le suivant :

graph
  A[Créer/Modifier un Markdown docs dans le dépôt] --> B;
  B[Ouvrir une pull request] --> C;
  C[Execution auto pipeline CI] --> D1;
  C --> D2;
  D1[Job: Validation synthaxe markdown] --> E;
  D2[Job: Verification des liens] --> E;
  E[Job: déploie une preview de la docs] --> F;
  F[Revue/validation par un collaborateur de la pull request] --> G;
  G[Merge et publication automatique sur Github/Gitlab Pages]

Resources¶

Pour explorer davantage l'art de la documentation, je vous recommande de parcourir writethedocs. writethedocs aggrége de nombreux guides, il y aura surement des réponses à vos interrogations.