Importance d’une documentation technique utile

Qui n’a jamais perdu de précieuses heures à essayer de comprendre une fonctionnalité ou comprendre un concept ? Et tout cela, uniquement parce que la documentation technique n’était pas claire. Pire, absente.

Que ce soit pour implémenter une API ou même déboguer un outil, une documentation technique bien rédigée peut faire toute la différence pour garantir la compréhension, la maintenance et l’évolution des projets.

Seulement voilà, rédiger une documentation technique utile demeure un défi pour bon nombre de développeurs.
Un problème de méthodologie peut en effet rendre l’exercice fastidieux. Alors qu’il n’en est rien. Comment dès lors parvenir à rédiger une documentation technique vraiment utile ?

Fort de mon expérience de Tech Lead, je vous propose quelques pistes simples qui conditionnent une bonne rédaction. A savoir, la cible, la portée et la structure.

Rédiger la documentation technique pour un public cible

Qui va lire votre documentation ? La réponse est simple, personne !

En tout cas, pas dans un premier temps : ils regarderont les images et/ou copient/colleront le code.

La plupart des utilisateurs d’un outil ne lira la doc que lorsqu’ils n’arriveront pas à faire ce qu’ils veulent.

Savoir qui va lire votre doc et à qui elle est destinée va vous permettre de savoir quel vocabulaire utiliser et quel niveau de vulgarisation employer (si la doc est technique).

Indiquer dès le début (première page ou home page) qui est la cible de la doc. Si vous adressez plusieurs publics, n’hésitez pas à mettre des quick links vers les zones qui peuvent les intéresser.

Exemple, en introduction de documentation :

Définir l’objectif de votre documentation technique

Avant de faire quoi que ce soit d’autre, vous devez vous arrêter et réfléchir à la raison pour laquelle vous êtes sur le point d’écrire une documentation technique.

Avant d’entreprendre quoi que ce soit, prenez le temps de réfléchir à la raison pour laquelle vous vous prêtez à cet exercice. Une documentation sans périmètre clairement défini peut en effet être très déroutante.

Entre un tutoriel et une documentation complète, on ne va pas aborder le sujet de la même façon.

Le choix du titre doit aussi prendre en compte ce paramètre afin d’indiquer à l’utilisateur dans quelle lecture il se lance. Un guide de démarrage rapide de 20 pages n’ayant pas forcément de sens.

Définissez correctement le périmètre de votre doc, quitte à ce qu’il évolue un peu plus tard. Bien que cela soit difficile à faire, ce périmètre vous aidera aussi à rester concentré sur l’essentiel et ne pas trop vous éparpiller.

Exemples :

Sur un guide

How to Deploy a Symfony Application

Deploying a Symfony application can be a complex and varied task depending on the setup and the requirements of your application. This article is not a step-by-step guide, but is a general list of the most common requirements and ideas for deployment.

Sur un mode opératoire

Spring Quickstart Guide

What you’ll build

You will build a classic “Hello World!” endpoint which any browser can connect to. You can even tell it your name, and it will respond in a more friendly way.

What you’ll need

An Integrated Developer Environment (IDE)

Popular choices include IntelliJ IDEA, Spring Tools, Visual Studio Code, or Eclipse, and many more.

A Java™ Development Kit (JDK)

We recommend BellSoft Liberica JDK version 17.

Sur une documentation générale

API reference documentation

The API reference documentation provides detailed information about a function or object in Node.js. This documentation indicates what arguments a method accepts, the return value of that method, and what errors may be related to that method. It also indicates which methods are available for different versions of Node.js.

Structurer la documentation technique

Comme vous devez vous en douter, c’est une mauvaise idée de tout regrouper sur la même page.

L’organisation de vos documentations doit aider les lecteurs à accéder rapidement à l’information recherchée. Une erreur fréquente est d’organiser la documentation en suivant les étapes de création ou en partant de la définition du besoin.

Personne ne s’intéresse aux conditions générales d’utilisation, de vente ou aux détails sur la genèse de ce que vous documentez.

La structure de votre doc doit plutôt refléter la façon dont elle va être utilisée en s’appuyant sur des modèles d’organisations connus.

La documentation technique : tout un art pour rationaliser la communication

En somme, concevez la rédaction d’un document technique comme une activité de communication. Un peu comme les écrivains ou les cinéastes… Ils réfléchissent toujours à un public cible lorsqu’ils démarrent un récit. C’est la même chose. Cela exige de votre part, également, de
définir clairement le périmètre couvert par votre documentation. Ces étapes préliminaires permettront d’emblée à toutes les parties prenantes d’avoir une idée précise de votre contenu.

En suivant ce cadre, vous serez sur la bonne voie pour proposer, en bon communiquant et bon développeur, une documentation conviviale, accessible et utile à tous.