Journal Jacob Kaplan-Moss: Écrire une bonne documentation

Posté par . Licence CC by-sa
Tags :
25
7
nov.
2012

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.

  • # La base de la base

    Posté par . Évalué à  10 .

    Il manque à mon avis le truc basique qu'on trouve rarement : commencer par expliquer le concept.
    Il y a un paquet de documentations qui ne prennent même pas la peine d'expliquer à quoi sert le produit/service/API/etc. Et qui ne prennent même pas la peine de décrire le fonctionnement général, le principe.

    On retrouve la même chose sur plein de sites web pour des logiciels (libres ou non). Il y a des news, des forums, un lien de téléchargement, tout ce qu'on veut… mais on ne sait pas à quoi sert le truc. Est-ce un logiciel "lourd", une bibliothèque, un élément utile uniquement en relation avec une autre chose bien précise ?

    • [^] # Re: La base de la base

      Posté par (page perso) . Évalué à  2 .

      À la lecture de ce journal, il m'avait semblé comprendre que le choix (discutable certes) de l'auteur était le suivant : aborder le sujet par des cas d'utilisation concrets au lieu d'une dissertation théorique. Cela se défend aussi. Surtout pour des gens ayant une expérience si faible de la rédaction qu'il doivent encore se poser des questions sur la mise en page (point 3), ignorant qu'ils peuvent déléguer cette problématique à leur éditeur (bientôt) favoris : Latex ;-).

      • [^] # Re: La base de la base

        Posté par . Évalué à  2 .

        Ce journal est un résumé, et non une traduction. Ce qui fait que beaucoup de références (cas concrets) sur lesquelles s'appuyer sont établies par l'auteur, et que je n'ai pas listé dans leurs totalités (bien que Latex n'étais pas indiqué à ma connaissance).
        En fait, l'auteur illustre la plupart du temps ses propos par un exemple. Mais cela reste une série d'articles, et non un ouvrage en la matière.

        Si certains ont lu ses articles, ce serait intéressant qu'ils me corrigent dans cet essai (peut-être aurais-je omis des informations importantes).

        • [^] # le bug de la doc

          Posté par (page perso) . Évalué à  4 .

          Juste en passant puisqu'on est dans la documentation, Quand je dois écrire des spécifications (C à D avant de seulement penser à la doc) je me réfère tout le temps à Painless Functional Specifications de Joel Spolsky (Mr Stack Exchange). C'est productif et c'est marrant - ça fait partie des trucs pour écrire de la bonne doc et surtout, faire en sorte qu'elle soit lue.

  • # Je ne peux pas laisser dire cela

    Posté par . Évalué à  2 .

    À 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).

    J'aime beaucoup python. Mais je ne peux pas te laisser dire cela. La doc Python est typiquement insuffisante: elle n'est justement pas exhaustive, on ne sait pas à quoi s'attendre comme retour, ni l'ensemble des valeurs possibles pour les paramètres, son périmètre d'utilisation, etc. Fouiller dans les sources pour savoir comment utiliser une méthode, ça va 5 minutes, mais ce n'est pas efficace.

    Une bonne doc technique, je trouve, c'est la doc QT qui est, elle, vraiment bonne et agréable à utiliser. C'est simple : tu sais que tu vas trouver la réponse à ta question.

    • [^] # Re: Je ne peux pas laisser dire cela

      Posté par . Évalué à  1 .

      En fait, l'exemple de la documentation Python (qui au passage est l'exemple de l'auteur de l'article, non du mien) est pour illustrer l'agencement entre la documentation simple, et la référence: je rappelle que dans ce chapitre, l'auteur conseillait de différencier ces 2 parties en 2 documentions distinctes (on ne parlait pas nécessairement des points positifs et négatifs que l'on peut établir à la lecture de la documentation).

      Sinon, en effet, QT est assez bien fait.

    • [^] # Re: Je ne peux pas laisser dire cela

      Posté par . Évalué à  2 .

      La doc Python est typiquement insuffisante

      Là, c'est moi qui ne peut pas te laisser dire ça : franchement, le tutoriel de Guido est un des meilleurs du genre, et la doc en général est vraiment bien. Elle n'est peut-être pas parfaite sur certains points, mais je ne la reconnais en tous cas pas du tout dans les défauts que tu édictes. Je n'ai que très très rarement aller dû voir dans les sources, et c'était vraiment pour des cas tordus.

Suivre le flux des commentaires

Note : les commentaires appartiennent à ceux qui les ont postés. Nous n'en sommes pas responsables.