Once-Only dans la documentation

Once-Only dans la documentation : comment le Documentation Engineering et le Docs-as-Code mettent en œuvre ce principe

Qu’est-ce que le principe Once-Only ?

Le principe Once-Only stipule : les données ou informations ne doivent être saisies, stockées et maintenues qu’une seule fois – et réutilisées à tous les endroits pertinents. Il évite la redondance, minimise les sources d’erreurs et réduit la charge de maintenance. Initialement connu dans l’administration publique et l’e-gouvernement, il gagne une importance croissante dans la documentation technique – en particulier dans les systèmes complexes, agiles et évolutifs.

Pourquoi le Once-Only est-il important dans la documentation ?

Dans les projets logiciels, la documentation se développe souvent de manière non coordonnée :

• La documentation API existe séparément des manuels utilisateur.
• Les diagrammes sont dessinés manuellement et ne sont pas synchronisés avec le code.
• Les notes de configuration sont dupliquées dans plusieurs documents.

Cela entraîne des incohérences, des contenus obsolètes et une charge de maintenance accrue. Le Once-Only apporte ici de la clarté :

Écrire une fois. Utiliser partout.

Documentation Engineering : la base du Once-Only

Le Documentation Engineering est l’approche systématique et ingénieriale de la documentation – axée sur la structure, la réutilisabilité et l’automatisation. Il permet :

• Des documents modulaires : le contenu est décomposé en blocs réutilisables (par exemple, « descriptions de composants », « codes d’erreur »).
• Des sources centrales : tout le contenu provient d’une source unique et maintenue (Single Source of Truth).
• Une liaison automatisée : le contenu est dynamiquement traduit dans différents formats de sortie (PDF, web, systèmes d’aide).

Exemple : Un point de terminaison API est décrit dans un fichier YAML. Celui-ci sert de source pour :

• La documentation Swagger/OpenAPI
• Les sections du manuel utilisateur
• La référence développeur
• Les tests automatisés

→ Aucune copie manuelle. Aucune incohérence. Une seule source.

Docs-as-Ecosystem : la documentation comme système vivant

Un Docs-as-Ecosystem considère la documentation non pas comme un artefact statique, mais comme un système intégré et dynamique, connecté au code, aux tests, au CI/CD et à la surveillance.

Caractéristiques d’un Docs-as-Ecosystem :

• Génération automatique : la documentation est générée à partir des commentaires du code, des fichiers de configuration ou des tests.
• Boucles de rétroaction : les utilisateurs peuvent donner leur avis directement depuis la documentation – par exemple via des boutons « Cette information était-elle utile ? ».
• Gestion des versions : la documentation est versionnée avec le code – aucune discrépance entre la version 1.2 et sa documentation correspondante.
• Recherchabilité et navigation : les contenus sont liés via des moteurs de recherche et une navigation intelligente – pas seulement lisibles de manière linéaire.

Impact sur le Once-Only : Chaque contenu fait partie d’un réseau. Les modifications à un endroit se répercutent automatiquement sur tous les documents dépendants – sans maintenance manuelle supplémentaire.

Diagrams-as-Code : les visualisations sous forme de code

Les diagrammes sont souvent la plus grande source de redondance :

• Un diagramme d’architecture est créé dans PowerPoint, puis inséré dans Confluence, puis copié dans un PDF.
• Lors des modifications, il doit être mis à jour manuellement partout.

Solution : Diagrams-as-Code

Avec des outils comme Mermaid, PlantUML, Graphviz ou Diagrams.net (avec export de code), les diagrammes sont définis sous forme de texte – et peuvent être intégrés à la documentation.

Exemple (Mermaid) :

graph TD
    A[Utilisateur] --> B[Passerelle API]
    B --> C[Service d'authentification]
    B --> D[Service de commandes]
    C --> E[Base de données]
    D --> E

→ Ce code peut être intégré dans Markdown, Sphinx, Docusaurus ou d’autres systèmes. → Les modifications du code mettent automatiquement à jour le diagramme dans tous les documents. → Aucune maintenance manuelle. Aucun graphique obsolète.

Docs-as-Code : la mise en œuvre technique du Once-Only

Le Docs-as-Code est la pratique qui consiste à traiter la documentation comme du logiciel :

• Versionné dans Git
• Automatisé avec CI/CD
• Validé par des tests
• Maintenu via des Pull Requests

Éléments clés :

• Dépôts de code source : la documentation réside dans le même dépôt que le code – ou dans un dépôt dédié mais lié.
• Constructions automatisées : à chaque modification, la documentation est régénérée et publiée.
• Validation : les liens sont vérifiés, la syntaxe est validée, les diagrammes sont rendus.
• Réutilisation : grâce à des mécanismes d’inclusion ou d’importation, les blocs de construction sont réutilisés dans plusieurs documents.

Exemple avec Antora (AsciiDoc) :

.. include::requirements.adoc

Les modifications apportées à requirements.adoc affectent tous les documents qui l’incluent.

Mise en œuvre pratique : étape par étape

1. Identifier les contenus redondants → Quelles sections sont copiées plusieurs fois ? Quels diagrammes existent en plusieurs versions ?

2. Créer des sources centrales → Regrouper les contenus récurrents dans des fichiers réutilisables (par exemple, shared/, components/).

3. Choisir des outils prenant en charge Docs-as-Code et Diagrams-as-Code → Markdown + Mermaid (ou AsciiDoc + PlantUML) + Git + CI/CD (par exemple, GitHub Actions, GitLab CI).

4. Intégrer la documentation dans le processus de développement → Toute modification de code affectant l’API nécessite une modification de la documentation – dans le cadre de la Pull Request.

5. Automatiser la validation et la publication → Vérifier les liens, la syntaxe, les diagrammes. Publier automatiquement sur un site de documentation.

6. Mettre en place des mécanismes de rétroaction → Les utilisateurs peuvent donner leur avis directement depuis la documentation – par exemple via des GitHub Issues ou des formulaires intégrés.

Conclusion : le Once-Only n’est pas un luxe – c’est une nécessité

Dans un monde où le logiciel est en constante évolution et expansion, la documentation manuelle n’est plus viable. Le Once-Only est la réponse :

• Efficacité : moins de travail, moins d’erreurs.
• Cohérence : tous les utilisateurs voient le même état à jour.
• Évolutivité : la documentation grandit avec le système – sans effort supplémentaire.

Avec le Documentation Engineering, le Docs-as-Ecosystem et le Docs-as-Code, le Once-Only devient non seulement possible – il devient le fondement d’une documentation moderne et vivante.

• ←Précédent
• Suivant→