Comment bien documenter un système informatique ?

Je crois que je n’ai jamais écrit un titre aussi pompeux.

Enfin bref, cet article s’appuie sur différentes expériences que j’ai vécues … avec plus ou moins de succès.

Avant tout, posons la situation.

Quelques hypothèses

  • Vous faites partie d’une équipe de développement logiciel (je ne sais pas si ce que je vais décrire ici marche dans d’autres situations)
  • Vous disposez d’un outil de build moderne (Maven, Gradle, ou tous leurs équivalents)
  • Je vais parler ici de système, plus que de logiciel, parce que la plupart du temps, vous développez plusieurs logiciels livrables : un site web, un back-end, des plugins ou des applications clientes, …
  • Le système que vous développez est unique : personne d’autre dans le monde ne fait le même système que vous en utilisant les specs à votre disposition (ou pas)
  • Vous pouvez créer un nouvel artefact dans votre base de code pour stocker la partie principale de votre documentation

Quelques prises de conscience utiles

Vous avez donc, que vous utilisez une méthode agile ou en V, commencé par définir l’architecture de votre système avant de développer le code, qui a donné lieu à une structure de données.

Ca, c’est pour le système que vous allez livrer. Mais avez-vous conscience de l’autre système ?

6bwCQwX

Parce que vous faite quoi de votre gestionnaire de source ? De votre chaîne d’intégration et de déploiement continu ? A ce que je sache, ces éléments sont au minimum configurés pour votre équipe (dans le cas de git, ça va vite), et dans la plupart des cas hautement personnalisés selon vos besoins. Typiquement, vous avez deux systèmes à documenter :

  1. Celui que vous allez livrer
  2. Celui qui vous permet de le livrer

Quelqu’un à l’esprit joueur pourrait y voir une forme d’inception : développer un logiciel avec un ensemble de logiciels qu’on est en train de développer …

Il vous faut documenter à la fois le système que vous livrez, et celui que vous utilisez pour livrer.

Par ailleurs, est-il judicieux de parler de votre système, ou des différentes incarnations de celui-ci ?

3Bm98kT

Parce qu’après tout, votre système va connaître de multiples incarnations :

  • Architecture logique ne décrivant que les différents composants de l’application hors de toute réalité
  • Architecture physique incluant les différents environnements
    • Environnements de dév,
      • de recette
      • de prod
    • Environnements locaux
      • en PAAS
      • dans des conteneurs Docker

Dans l’idéal, votre documentation doit pouvoir se projeter sur ces différents environnements.

Quelques outils et méthodes utiles

D’abord, mettons-nous d’accord pour dire que, comme tout le monde, vous n’avez pas envie de vous répéter. Heureusement, ce problème de la non répétition est connu depuis longtemps. Regardez par exemple cet article : Single Source Information: An Agile Best Practice for Effective Documentation. Il est un peu vieux et prône donc l’utilisation de Dita XML. Ne vous enfuyez pas tout de suite, je suis sûr que vous allez voir où je veux en venir.

Quel format de document source utiliser ?

Effectivement, il faut limiter les sources de documentation et multiplier au contraire les formats de sortie. Ca revient à dire qu’il ne faut pas utiliser Office pour créer de la documentation, et pour plusieurs raisons :

  • Le livrable et la source documentaire sont identiques
  • Le système de gestion de révision intégré est loin derrière les outils de développement à notre disposition
  • Le travail collaboratif est pratiquement impossible
  • La création de documents lourds ne marche pas
  • L’inclusion de données externes mobiles est difficile à maintenir

En face, évidement, il y a eu XML (avec Docbook et Dita). Eux aussi avaient leurs défauts

  • Une syntaxe lourde
  • Des include incroyablement difficiles à maintenir
  • La nécessité d’utiliser des éditeurs spécialisés

Du coup, on pourrait penser que LaTeX pourrait être une réponse. Malheureusement, je crois que sa syntaxe n’est pas vraiment légère.

Du coup, je recommande chaudement d’utiliser AsciiDoc.

  • La syntaxe est simple
  • Il est possible de créer des structures de documents complexes (avec les include de fragments de documents)
  • Il existe des éditeurs WYSIWYG (comme par exemple AsciidocFX) qui facilitent réellement la montée en compétence
  • Et enfin, les documents finaux peuvent être générés pendant le build de votre projet, ce qui permet de raprocher la documentation et le code

Comment dessiner les diagrammes ?

Evidement, ce qui vaut pour les documents vaut également pour les diagrammes : pourquoi utiliser Visio, yEd pour des diagrammes qui vont être partagés ?

Coup de bol, asciidoctor fournit une bibliothèque (asciidoctor-diagram) qui permet de générer un paquet de type de schémas différents en intégrant quelques bibliothèques bien pratiques, et en particulier PlantUML. C’est d’autant plus intéressant que ça limite, par la nature textuelle du diagramme, la taille du dessin qui va être créé (parce que je sais pas vous mais personnellement, quand je vois un diagramme avec plus de dix noeuds, je commence à pleurer un peu).

Quel plan utiliser ?

On arrive à l’une des questions cruciales.

Avant tout, une bonne documentation, c’est une bonne histoire. Par conséquent, tout plan de documentation qui ne permettra pas l’exposé de l’histoire du système ne pourra pas être un bon plan. Et par histoire, je ne veux pas dire son historique des décisions. Non, je parle d’une histoire au sens le plus journalistique du terme : qui ? quoi ? quand où ? comment ? et surtout pourquoi ? Si votre plan ne contient pas ces éléments sous une forme ou une autre, vous n’y arriverez pas.

Coup de bol, j’ai le bon plan. ou plutôt Simon Brown a le bon plan.

Vous connaissez Structurizr ? Non ? Eh bien allez y faire un tour, c’est très intéressant.

En revanche, à titre personnel, comme j’aime mettre plus de texte que de diagramme, je trouve sa page Documentation encore plus intéressante. Pour une raison en particulier : il y décrit le contenu d’une bonne documentation sous la forme d’un sommaire assez bien fichu. Le voici :

  1. Context
  2. Functional Overview
  3. Quality Attributes
  4. Constraints
  5. Principles
  6. Software Architecture
  7. Code
  8. Data
  9. Infrastructure Architecture
  10. Deployment
  11. Development Environment
  12. Operation and Support
  13. Decision Log

Eh bien le plan que je vous propose de suivre, c’est celui-là précisément.

Mais comment tout ça s’organise ?

Créer un artefact de documentation pour le système livrable

Dans votre gestionnaire de source, créez votre artefact de documentation. Généralement, je crée un module maven sous le projet principal. Si j’ai plusieurs sous-systèmes, je vais créer un module maven par sous-système et les agréger ensuite par chapitre (si le chapitre existe) au niveau principal

Pour ma part, ce sera un projet maven dans lequel je vais tout de suite ajouter le plugin asciidoc avec la configuration nécessaire pour générer du PlantUML.

Dans le dossier des sources asciidoc (donc dans mon cas dans src/docs/asciidoc), créez un dossier include dans lequel vous créez un fichier asciidoc pour chacun des chapitres de la doc.

Ecrivez votre doc

Pour chacun de ces chapitres, commencez par décrire le système d’une façon générale. Ne plongez dans les détails que si ces détails sont pertinents.

Ou générez votre doc

Il y a tout un tas d’éléments pour lesquels il peut être pertinent de générer certains éléments :

  • des diagrammes de classes extraits du code
  • des listes de classes implémentant certaines interfaces (avec des propriétés utiles)

Par pitié, ne vous répétez pas : vous pouvez, et devez, générer ces informations en asciidoc à partir de votre code.

Pour ça, j’utilise de façon systématique groovy : avant la génération de la doc, j’ai des scripts Groovy qui vont générer (dans target/generated/docs) les différents documents utiles.

Générez la doc livrable

Comme les fichiers asciidoc sont dans votre doc et utilisent le même système de build, vous pouvez générer la doc à chaque livraison, et même l’inclure comme artefact de votre build.

Ca vous garantit une documentation

  • à jour (puisqu’il est facile pour les développeurs de la modifier
  • propre (parce que Asciidoc génère facilement quele chose de joli)
  • conforme aux différents besoin de doc (puisqu’on peut facilement inclure les différentes parties de la doc dans différents documents)

Et ça marche bien ?

Chaque fois que j’ai utilisé cette méthode, j’ai réussi à produire de la documentation efficace, propre, et complète. Je ne sais pas si c’est une preuve

Mais où documente-t-on le système de développement ?

Dans la partie Development Environement, tout simplement.

Ca n’est pas un peu fastidieux de tenir à jour les diagrammes PlantUML ?

Ca peut rapidement l’être, c’est pour ça que je vous présenterai bientôt les différentes solutions auxquelles je pense pour … les générer, évidement ! (je dois d’ailleurs les tester sur mes programmes Codingame).

Tout ça n’est pas un nouveau nom sur une vieille idée ?

Bien sûr que si. L’idée, c’est le litterate programming, qui a connu des dizaines d’incarnation. Celle-ci est juste un peu plus moderne.

Publicités

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s