Comment produire une documentation de qualité ?

Ah, la documentation… Quel joyeux sujet.

Tout le monde en veut. Pour tout. Et pourtant, personne n’aime ça. Je vous vois déjà tourner les talons en grommelant. JE SAIS ! Quel intérêt de lire un article sur un sujet aussi rébarbatif ?

Mais tout d’abord, pourquoi est-il si rébarbatif ? Après tout, il s’agit d’abord de comprendre le fonctionnement d’un système. Et comprendre, ça peut être intéressant. Tout dépend de l’angle utilisé pour présenter les informations, de l’intérêt que porte celui qui écrit et celui qui lit, ainsi que tout un tas de petites astuces qui permettent de passer, de la documentation qu’un consulte en dernier recours, à la documentation avec laquelle on apprend. Voyons si nous pouvons rendre la chose un peu moins pénible.

Qu’est-ce que la documentation ?

Définition

Documentation, nom féminin

Sens 1 Ensemble de documents. Anglais paperwork, papers

Sens 2 Notice, brochure. Anglais documentation

Sens 3 Fait de se documenter, de rechercher des documents. Anglais research

Vous en conviendrez… cela veut tout et rien dire. Et c’est précisément le problème.

Le problème

La consigne la plus fréquemment donnée : «Ah et n’oubliez pas de bien me documenter tout ça, hein !»

Très bien… mais documenter quoi ? Et pour qui ?

Celui qui demande la documentation est au final rarement son destinataire.

Le résultat

Un amas de documents pondus en début de projet, rapidement obsolètes et donc jetables, ou en fin de projet, souvent bâclés et ensuite jamais mis à jour.

On en arrive souvent à la conclusion que la documentation, c’est cher à écrire, et pénible à lire…

Maintenant, prenons le problème à l’envers

Quand vous installez un nouveau logiciel, combien de temps passez-vous à lire la documentation avant de commencer à l’utiliser ?

Quand vous arrivez sur un projet, à quoi vous fiez-vous ? A la documentation ou au code ?

La documentation est-elle donc inutile ?!

Non, évidemment. Néanmoins, il s’agit de la cibler : à qui s’adresse-t-elle ? Et sous quel angle l’aborde-t-on ?

Ce que dit le manifeste agile

«Working software before comprehensive documentation». Cela ne veut pas dire «pas de documentation». Simplement qu’elle est moins prioritaire qu’un logiciel opérationnel. Cela conduit néanmoins à repenser la documentation.

Quelle documentation ?

La Big Picture

Elle est destinée à tout le monde. Comme souvent, elle répondra au principe « Less is more« . En effet, elle doit résumer le périmètre du projet, sa baseline, en une seule phrase simple. Si ce n’est pas le cas, le périmètre est-il réellement bien cadré ?

La documentation utilisateur

La seule à laquelle vous ne couperez jamais. Mais variez les supports ! Soyez créatif ! Privilégiez la documentation embarquée dans le logiciel plutôt que le pavé broché qui prendra la poussière dans un placard. Démos, vidéos, tutoriels embarqués dans le logiciel…

Lisez-vous systématiquement la documentation d’un matériel ou d’un logiciel avant de vous lancer ? Bien sûr que non. La documentation utilisateur doit faire l’objet d’une réelle réflexion très tôt dans le projet et gagne à être fortement liée à la réflexion sur l’ergonomie générale.

Quelques bons exemples : Dropbox, SensCritique, les tutoriaux « in game » des jeux vidéo récents…

Le suivi de projet

La documentation de suivi de projet est destinée aux managers et aux membres du projet. Elle peut être naturellement produite pendant le projet par les intervenants, comme dans Scrum, en utilisant des outils simples et appropriés, que ces derniers soient logiciels ou matériels.

De cette façon, la production de la documentation de suivi de projet est indolore et construite en temps réel.

La documentation technique

Celle-ci est à destination des développeurs et d’eux seuls. Les développeurs peuvent être internes au projet, mais aussi externes, lors de la mise à disposition de services web ou d’un framework, par exemple.

On distinguera 2 cas :

  • La documentation d’architecture, qui se résumera à un ensemble de schémas, de diagrammes et de listes
  • La documentation exhaustive, pouvant être générée automatiquement
Le but de la documentation technique est d’accélérer les développements de nouvelles fonctionnalités. Le développeur doit donc y trouver son compte et avoir confiance dans ce qu’il lit. Elle doit systématiquement être à jour et claire. Pas de ronds de jambes, pas de chichis. La réponse doit venir rapidement.

Génération automatique de la documentation technique

Comment s’assurer de la qualité de la documentation ?

  • Elle doit être synchrone avec le code
  • Elle doit être écrite en même temps que le code.
  • Elle doit être lisible à partir du code et de l’extérieur : c’est la multidiffusion.
Quelques exemples publics : la JavaDoc, MSDN, phpDocumentor, Amazon EC2 API Reference.
Au final, la seule vraie bonne documentation est écrite directement dans le code. C’est la seule façon de satisfaire l’ensemble des contraintes.

Utiliser les tags de documentation C#

<summary> : la synthèse

<param> : détail d’un paramètre

<returns> : détail de l’objet retourné

<exception> : exceptions retournées

<code> : portion de code

<example> : exemple d’utilisation

L’ensemble des tags existants sont détaillés sur la MSDN. Lors de la compilation de la solution, il est possible de demander la génération des données brutes de documentation en sélectionnant l’option « XML documentation file » dans l’onglet Build des propriétés de chacun des projets d’une solution.

Ecriture, extraction et diffusion de la documentation

Voici quelques solutions permettant de générer votre documentation pour vos projets .NET :

GhostDoc : un utilitaire fort pratique d’aide à la saisie de la doc C#.

SandCastleHelpFileBuilder : une surcouche de SandCastle, permettant d’extraire et d’afficher la documentation sur de multiples supports (CHM, HTML, XML…) à partir des fichiers XML produits au point précédent. C’est de cette façon que Microsoft met automatiquement à disposition sa MSDN.

Pour aller plus loin

Les exigeances et les tests fonctionnels peuvent être réunis au sein d’un même outil, comme FitNesse.NET ou GreenPepper. Ces outils permettent d’écrire en langage naturel des tests d’exigence. Avec quelques conventions, on peut donc écrire simplement des scénarios utilisateur du type « en tant que X, je peux effectuer l’opération Y afin d’obtenir le résultat Z ». Et ainsi obtenir une documentation exécutable (ou spécification exécutable). Nous en reparlerons rapidement…

2 Commentaires Laisser un commentaire

[…] Comment produire une documentation de qualité ? | Cellenza Tout dépend de l'angle utilisé pour présenter les informations, de l'intérêt que porte celui qui écrit et celui qui lit, ainsi que tout un tas de petites astuces qui permettent de passer, de la documentation qu'un consulte en dernier … Source: http://www.cellenza.com […]

Répondre

[…] encore, je vous renvoie vers cet article traitant du sujet. La documentation technique doit être écrite par les développeurs directement dans l’IDE, […]

Répondre

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *