Comment produire une documentation technique de qualité ?

Ah, la documentation technique d’un projet… Quel joyeux sujet !

Tout le monde en veut et 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, la documentation technique permet de comprendre le fonctionnement d’un système, d’un logiciel ou encore d’un service. 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.

Mais cela dépend aussi de tout un tas de petites astuces qui permettent de passer, de la documentation qu’on consulte en dernier recours, à la documentation avec laquelle on apprend.

Pour rendre la création et la lecture de la documentation technique de nos prochains projets informatiques le moins pénible, suivez les conseils de cet article !

Qu’est-ce que la documentation technique ?

Avant de se lancer dans la résolution de notre problème, intéressons-nous à la définition de la documentation technique.

Définition de la documentation technique

Documentation technique, 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 de la documentation

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 document sans valeur

Sans consigne précis, la documentation technique IT devient rapidement 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.

Voilà pourquoi 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 technique 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 technique informatique choisir ?

C’est un fait, la documentation technique reste un document utile qui doit répondre à un besoin identifié. Pour y arriver et créer un document qui ne finira pas à la poubelle, il faut choisir le type de documentation qui correspond le mieux à la cible pour laquelle vous rédigez ces lignes.

La documentation “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, posez vous la question du 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, … Mettez-vous à la place de l’utilisateur, plus vite il comprendra le fonctionnement de votre système, site web ou encore application, plus vite il sera conquis par ce dernier et reviendra l’utiliser.

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 exemples de documentation utilisateur

Afin d’illustrer ce que doit être une bonne documentation utilisateur, mais surtout pour vous donner des idées, voici quelques bons exemples que vous pouvez analyser :

• La documentation utilisateur de Dropbox : les textes sont cours, les parties bien structurées, le fil d’Ariane permet à l’utilisateur de retrouver facilement ce qu’il cherche.

• La documentation utilisateur de SensCritique : elle se tient sur une page et se structure en partie correspondant aux grandes “fonctionnalités” du site. L’utilisateur n’a plus qu’à cliquer pour retrouver la solution à son problème.

• Les tutoriaux “in game” des jeux vidéo récents :

La documentation 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 notamment dans les projets agiles 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 des développeurs

Comme son nom l’indique, elle 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 : elle résumera à un ensemble de schémas, de diagrammes et de listes
• La documentation exhaustive : elle peut être générée automatiquement

Documentation technique : la génération automatique

On l’a vu, créer une documentation technique n’est pas une tâche à prendre à la légère. Bien que cela peut-être contraignant, il est aujourd’hui possible de se servir d’outils ou de suivre certaines astuces pour générer automatiquement la documentation technique informatique de votre système, solution, …

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 ce qu’on appelle la multidiffusion

Utilisation  des tags de documentation C# et extraction des fichiers XML

Afin de simplifier l’écriture, vous pouvez spécifier vos lignes de codes en utilisant les tags suivants :

• <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

Vous pouvez retrouver l’ensemble des tags existants sur la documentation Microsoft des tags recommandés en C#.

Lors de la compilation de la solution, il est possible de demander la génération des données brutes de documentation. C’est une configuration à réaliser pour chacun des projets de la solution. Voici les étapes à suivre sur l’IDE Visual Studio :

• Visual Studio 2013/2015 : Propriété du projet > Build > Output > Cocher “XML documentation file” et renseigner ensuite le chemin du fichier XML

• Visual Studio 2022 : Propriété du projet > Build > Sortie > Cocher “Générez un fichier contenant la documentation de l’API” et renseigner le chemin du fichier XML

Écriture, extraction et diffusion de la documentation technique

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#.
• Sand Castle Help File Builder (SHFB) : cette surcouche de SandCastle permet 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 ses documentations. Pour en savoir plus, voici le repo GitHub de SHFB.

Documentation exécutable et documentation pour les APIs

Les exigences et les tests fonctionnels peuvent être réunis au sein d’un même outil, comme par exemple 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).

Au delà de la documentation d’une application web client lourde, on peut également générer de la documentation pour les APIs avec la solution Swagger. Si ce sujet vous intéresse, l’article “Comment se matérialise techniquement une API” présente son fonctionnement et sa mise en place.

Documentation technique : le document de référence à maîtriser

Rédiger une documentation technique digne de ce nom n’est certes pas simple, mais primordiale pour votre projet, solution, application ou encore système, d’autant plus si il est conçu pour être accessible par d’autres personnes !

Pour y arriver correctement, rien de mieux que de penser à sa cible et aux différentes interrogations qu’elle pourra se poser au moment d’utiliser ce qui est mis à sa disposition. Avant de se lancer dans la rédaction de ce document de référence, pensez donc à choisir la bonne documentation technique ou bien à vous servir de la génération automatique si vous devez réaliser une documentation technique pour des développeurs.