Écrire une doc technique utile
Tags: documentation, french
Published: 2024-02-27 08:06:17

L'é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](https://dev.to/arcanneero/series/26267). 

Des conseils pour le style d'écriture :

* J'ai rien pour le moment, proposez des trucs

Concernant les chartes graphiques et les visuels :

* [Memo design RGAA](https://design.numerique.gouv.fr/outils/memo-design/)

Un framework pour rédiger des docs techs (que l'on m'a conseillé) : https://diataxis.fr/