Yann SchepensL'écriture d'une doc, qu'elle soit technique ou non, est un exercice souvent difficile.
Elle l'est d'autant plus qu'il est naturel de la souhaiter compréhensible, logique, abordable et surtout utile.
Comme tout bon développeur, prenant le temps de concevoir avant de développer, je vous propose ces quelques conseils avant de vous lancer dans vos rédactions.
Nous aborderons seulement les aspects contenus de la doc, pas les aspects visuels, chartes, etc. Pour ça, orientez-vous plutôt sur les documents d'accessibilité.
Qui va lire votre doc ?
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 intro de documentation
About documentation
There are several types of documentation available on this website:
* API reference documentation
* ES6 features
* Guides
* Dependencies
De quoi parle votre doc ?
Rien de pire qu'une doc dont on n’identifie pas le périmètre. Entre un tuto et une doc 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 en compte afin d'indiquer à l'utilisateur dans quelle lecture il se lance. Un quickstart 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. Même si c'est difficile à faire, ce périmètre vous aidera aussi à rester concentré sur l'essentiel et ne pas trop vous éparpiller.
Exemples :
Sur un guide : https://symfony.com/doc/current/deployment.html
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 : https://spring.io/quickstart
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 : https://nodejs.org/en/docs
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.
Comment structurer votre doc ?
Comme vous devez vous en douter, c'est une mauvaise idée de tout mettre sur la même page.
L'organisation de vos documentations doit permettre aux lecteurs de trouver le plus rapidement possible l'information qu'ils cherchent. 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 lit les CGU/CGV et histoire de la création de ce que vous documentez.
La structure de votre doc doit donc refléter la façon dont elle va être utilisée en s'appuyant sur des patterns d'organisations connus.
Conclusion
Définir la cible et le périmètre de votre documentation est une première étape pour permettre aux lecteurs de savoir ce qu'ils vont trouver dans vos écrits.
Ce cadre va vous aider sur la façon dont vous allez rédiger et structurer votre documentation.
Dans un prochain article, je vous proposerai une façon d'organiser tout ça pour rendre l'information accessible rapidement et avoir une documentation utile !
Aller plus loin et un peu sur le côté
Je vous conseille l'excellente série d'articles de @arcanneero (Nicolas Giraud) si vous voulez vous lancer dans la doc as code.
Des conseils pour le style d'écriture :
- J'ai rien pour le moment, proposez des trucs
Concernant les chartes graphiques et les visuels :
Un framework pour rédiger des docs techs (que l'on m'a conseillé) : https://diataxis.fr/
