La première chose que je considère avant d'écrire une documentation est son audience : pour qui faut-il écrire ? À qui s'adresse ce texte ? Même ce blog nécessite que je réponde à la question. [1]
Certes il est possible qu'une documentation réponde aux besoins d'audiences différentes, cependant elle doit être structurée pour : avec des chapitres, ou des sections, clairement identifiés.
C'est d'ailleurs une erreur que je rencontre assez fréquement, car mêmes avec les meilleurs intentions du monde, les débutant·es ont tendance à se précipiter dans l'écriture avant de considérer le "pour qui". Par exemple en écrivant un document qui explique comment utiliser un outil en ligne de commande sans expliquer ni à quel besoin elle répond, ni les prérequis nécessaires. Cela génère confusion et frustration chez tout le monde : est-ce que quelqu'un est censé connaître cette commande ou est-ce seulement à usage interne ?
Au final, personne n'est vraiment satisfait, puisque les utilisateur·rices doivent se tourner vers les responsables du projet (entrainant la perte de temps que la documentation est censée éviter), tandis qu'en interne écrire la documentation démotive tellement elle semble redondante avec les connaissances de l'équipe. [2]
La responsabilité de l'auteur·ice de la documentation est avant tout de comprendre les besoins et les motivations de son audience, et d'adapter son écriture (le contenu, le niveau de précision, l'orientation, le déroulement, etc.) à cette audience. Le mieux est d'ailleurs de se concentrer sur une seule audience à la fois, en essayant de se mettre à sa place.
Cette approche est d'autant plus intéressante qu'elle permet de poser un cadre à son écriture :
- Connaître le niveau de connaissance de son audience permet de savoir ce qui doit être écrit, et ce qui peut faire l'objet d'une référence (un lien).
- Connaître le niveau de compétence de son audience permet d'ajuster le lexique, le niveau de jargon, et la quantité de détails nécessaires.
- Connaître les objectifs de son audience permet de répondre aux bonnes questions et de prioriser ce qui doit être écrit.
Une partie de ces questions peut (et devrait) nécessiter un peu plus que simplement se mettre à la place de l'audience. Après tout, j'ai beau écrire régulièrement, je suis fréquemment surpris par des questions auxquelles je n'aurais pas pu penser avec mon propre niveau de connaissance et de compétence du sujet.
C'est aussi pour ça qu'il est très difficile d'écrire une FAQ avant d'avoir publié son projet. Et ce pour quoi il ne faut jamais considérer que la documentation est complète tant qu'elle n'est pas utilisée.