Journal Jacob Kaplan-Moss: Écrire une bonne documentation

Faisant suite à la dépêche de CrEv qui n'était pas contre un retour sur un lien posté, j'en profite pour l'établir dans ce journal.

Source : http://jacobian.org/writing/great-documentation/

Écrire des documentations de qualité

Jacob Kaplan-Moss, fort de son expérience sur la rédaction de Django Book, ouvrage libre sur le framework Web Django fait en Python, nous livre une série d'articles sur les outils, astuces et techniques qu'il a appris au cours de ces années qu'il a dépensées dans l'écriture de la documentation Django (entre autres).

Il décompose ces séries en 3 parties :

1- Quoi écrire ?
2- Style d'écriture.
3- Vous avez besoin d'un éditeur.

Je vais tâcher de résumer rapidement ces chapitres.

1- La première partie donne la composition d'un bon tutoriel : « Be quick, Be easy, But not too easy », que l'on peut aisément réduire ainsi : Soyez rapide, simple, et adapté. Allez à l'essentiel, sans être trop laxiste. En d'autres termes, l'utilisateur final a besoin d'un tutoriel qui lui apporte une expérience rapide de l'objet, sans lui rendre la tâche ardue avec des incompatibilités, tout en sachant à qui s'adresse ce tutoriel (au risque qu'un novice en programmation se plante plus loin dans le tutoriel à cause de ses carences techniques).
La progression doit être souple, et non abrupte, tout en survolant les différentes facettes du projet.

Le tutoriel doit s'affranchir de guides thématiques, survolant ainsi différentes situations, et besoins, pas nécessairement tous les cas de figures (voir les titres des chapitres du Django Book).

Le tutoriel doit s'accompagner d'une référence complète pour toutes les API publiques que le projet prévoit. Ce document de référence ne doit pas se substituer au tutoriel : savoir qu'une fonction existe sans l'accompagner d'une explication n'a pas vraiment d'intérêt. À titre d'exemple, la documentation Python est parfaite (constatez que le document de référence ne se substitue pas au tutoriel et que, sans ce dernier, le premier reste difficile d'accès).

Enfin, l'auteur termine cette première partie par son avis sur les documentations auto-générées qu'il considère plus qu'inutile (that auto-generated documentation is worse than useless).

2- La seconde série se concentre sur le style d'écriture nécessaire à la production de bons guides techniques.

L'auteur débute par un constat indéniable : pour savoir bien écrire, encore faut-il s'exercer dans l'écriture en général. Multiplier l'expérience dans l'écriture fait progresser (dans son cas, son diplôme en littérature lui a donné de bonnes occasions de s'améliorer et d'adopter son propre style littéraire).
L'écriture sans la lecture n'est pas jouable non plus : savoir identifier ce qui marche, ce qui rend réceptif le lecteur. Jacob cite Malcolm Gladwell pour son style d'écriture distinctif, et qu'il qualifie de très bien pour la documentation technique, sans oublier les différences entre la fiction et non-fiction, la critique littéraire et la documentation technique. Selon lui, l'écriture doit être "simple, claire, et communiquer des idées efficaces" (good writing is clear, succinct, and communicates ideas effectively).

La grammaire n'est pas mise de côté, et l'auteur nous expose quelques références en matière de grammaire américaine.
Concernant le code typographique, celui utilisé pour la documentation django se réfère à l'AP Stylebook.

Puis, dans de très longs paragraphes, Jacob nous donne quelques astuces pour la documentation qui est consommée en ligne et qui diffère grandement dans celle utilisée avec des appareils comme tablettes, liseuses, etc. Ces astuces dans le style du texte (accents, mise en gras, nombreux paragraphes courts…) s'adaptent à la façon dont le lecteur utilise la lecture en ligne.

S'ensuit une liste de suggestions comme, par exemple, d'adopter un ton conversationnel, personnel (emploi du "je"), tout en faisant attention dans le fait de s'adresser au lecteur (emploi de la deuxième personne et au futur), d'éviter la passivité (être conscient que l'on instruit via le tutoriel), les sens vagues dans les phrases et de faire attention à ses tics (ici l'auteur nous avoue que ce sont les tirets _).

3- Enfin, la dernière série donne quelques conseils sur la façon de rédiger : à l'instar des auteurs qui ont un éditeur pour leur corriger leurs fautes, le rédacteur technique devra se concentrer sur la rédaction (désactiver la correction pour éviter d'être perturbé), puis à l'issue vérifier les fautes, laisser reposer la pâte (obtenir un certain recul dans la relecture) et s'appliquer à la décoration (marges, etc.).

En conclusion, Jacob apporte, dans cette longue série d'articles, les rudiments qui permettent de progresser dans la rédaction de documents plus en adéquation avec un lecteur à la recherche d'une bonne compréhension de son projet. Certes, tous les points ne sont pas détaillés, mais cela à le mérite d'être intéressant pour celui qui cherche à bien écrire.