Comment rédiger une bonne documentation - Le guide du débutant

Dernière mise à jour le
Écrit par : avatar de l'auteur Disha Sharma
comment rédiger une bonne documentation

Votre vie peut être beaucoup plus facile une fois que vous savez comment rédiger de la documentation - une bonne documentation, utile, qui donne réellement aux utilisateurs ce qu'ils attendent d'elle.

Après tout, tout le monde lit la documentation :

  • Les équipes marketing travaillent avec des playbooks - une sorte de documentation marketing. 
  • Les équipes d'assistance et les équipes techniques utilisent des guides d'utilisation, des manuels d'installation, des notes de code - la documentation technique "de base".
  • D'autres s'appuient sur des procédures opérationnelles standard, des documents de référence, des documents de processus, des listes de contrôle - la documentation typique des connaissances de l'entreprise.

Les clients utilisent eux aussi la documentation qui leur est destinée pour se familiariser avec une solution ou pour résoudre leurs problèmes par eux-mêmes (assistance de niveau 0).

Bien qu'il n'existe pas de méthode unique pour créer toute cette documentation, les étapes fondamentales restent les mêmes. Mais avant de les aborder, jetons un coup d'œil rapide aux différents types de documentation. En fonction de son objectif, un document peut être de l'un des quatre types suivants.

Icône de confiance

Nous testons et étudions rigoureusement chaque produit que nous recommandons sur HeroThemes. Notre processus d'évaluation. Nous pouvons également percevoir une commission si vous effectuez un achat par l'intermédiaire de nos liens.

Types de documentation

Dans son exposé sur les types de documentation, Daniele Procida ou Divio AG classe la documentation en quatre catégories :

  • des tutoriels axés sur l'apprentissage
  • des guides pratiques axés sur les objectifs
  • des discussions axées sur la compréhension
  • matériel de référence axé sur l'information

Comme vous pouvez le comprendre, chaque documentation a un objectif différent, et les responsables de la documentation doivent l'établir chaque fois qu'ils entreprennent d'en créer une.

Dans cette optique, commençons par notre guide sur la rédaction d'une documentation.

Déterminez si vous avez vraiment besoin de le documenter

Votre produit peut avoir une centaine de fonctions. Il peut y avoir encore plus de façons de le personnaliser. Vous pourriez avoir une base de code de plusieurs milliers de lignes. Et il se peut que vous génériez beaucoup de connaissances dans votre travail quotidien. 

Mais il n'est pas possible de tout documenter... et tout n'a pas besoin d'être documenté. 

Ainsi, avant de répondre à la question "comment rédiger une documentation", il convient de savoir si vous devez la documenter.

Avant de documenter, pensez à vos lecteurs cibles. Les lecteurs cibles de votre documentation peuvent être n'importe qui, de l'utilisateur final à votre (vos) développeur(s) de logiciels ou à votre personne chargée des ressources humaines. S'agit-il de travailleurs intellectuels? Réfléchissez à ce qui pose problème à ces publics cibles... et si vous pouvez réellement leur donner les moyens de faire mieux en documentant.

Pensez également à la façon dont ils l'utiliseront. Pensez à la manière dont les utilisateurs prévus interagiront avec votre documentation.

Vos clients suivront-ils votre documentation étape par étape pour commencer à utiliser votre solution ? Ce qui fait que votre documentation est "orientée vers un but".

Ou bien vos développeurs l'utiliseront-ils lorsqu'ils travailleront et collaboreront sur votre prochain cycle de publication ? Dans ce cas, vous avez affaire à une documentation "orientée vers la compréhension".

Ou bien votre service des ressources humaines s'y référera-t-il lors du traitement des candidatures ? Il s'agit ici d'une documentation "orientée vers l'information".

Et votre documentation les aidera-t-elle vraiment?

En outre, vous pouvez également réfléchir à la manière dont vos efforts de documentation vous aideront à un niveau plus élevé :

  • Votre documentation améliorera-t-elle votre support de niveau zéro et permettra-t-elle à vos utilisateurs finaux de résoudre leurs problèmes par eux-mêmes (déviation) ? 
  • Cela permettrait-il à vos équipes de s'améliorer dans leur travail ?
  • Votre équipe sera-t-elle plus productive ? 

Savoir quand le document doit être établi

L'idée générale est de ne pas commencer trop tôt (ou trop tard).

Si vous n'êtes pas sûr de la façon dont un processus va se dérouler ou de la façon dont vous allez exécuter votre "vision", il est préférable de ne pas le documenter et d'attendre que les choses se concrétisent un peu.

Par exemple, si vous prévoyez une mise à jour importante au cours du prochain trimestre et que le travail n'en est qu'au stade de la conception de haut niveau, n'engagez pas encore de ressources documentaires. 

C'est l'approche "Agile" de la documentation.

la documentation tout au long du cycle de développement durable (SDLC)

Souvent, le meilleur moment pour rédiger certains types de documents (comme les procédures et les processus) est celui où vous les mettez en œuvre. 

Se concentrer sur la meilleure façon de le documenter

Selon le type de documentation dont vous avez besoin, vous avez besoin d'un ou de plusieurs endroits pour la conserver. Ceux-ci constituent votre source unique de vérité. 

Chastity Blackwell, de Yelp, nous fait part de certaines frustrations liées au fait que toute votre documentation n'est pas bien rangée au même endroit :

Vous avez un document qui explique tout sur ce service et vous êtes sûr que l'information dont vous avez besoin pour résoudre cet incident s'y trouve - quelque part. "Vous pouvez essayer de le chercher dans le wiki, ou peut-être dans le répertoire Google Docs. Oh, et j'ai quelques notes dans mon répertoire personnel, et je crois que j'ai vu un courriel à ce sujet il y a quelque temps.

Naturellement, vous ne voulez pas que cela vous arrive. C'est pourquoi vous devez choisir votre (vos) outil(s) de documentation avec soin. Si vous documentez pour les utilisateurs finaux, il est préférable d'utiliser une solution de base de connaissances facile à remplir comme Heroic Knowledge Base.

Si vous documentez pour vos équipes, optez pour une solution wiki comme WikiPress ou une solution de gestion des connaissances interne, Heroic Knowledge Base (oui, c'est la même chose !). Vous pouvez également consulter les solutions de gestion des connaissances suivantes.

Enfin, si vous documentez du code, vous pouvez envisager des solutions de documentation technique et des systèmes de gestion de documents plus spécialisés. Certaines solutions de base de connaissances à usage général, comme Heroic Knowledge Base, fonctionnent tout aussi bien comme solutions de documentation technique.

Lorsque vous choisissez votre système de documentation, veillez à ce qu'il soit facile à mettre à jour, car vous risquez de devoir le faire souvent ! Votre outil de documentation doit également offrir d'excellentes fonctionnalités de recherche. 

Décider de ce qu'il faut écrire 

La documentation pouvant prendre de nombreuses formes, il est essentiel de définir un format avant de la rédiger. 

Par exemple, à l'adresse HeroThemes, nous utilisons un mélange de FAQ, de tutoriels d'installation, de guides de dépannage, de listes de conseils et d'astuces, etc. pour notre documentation destinée aux clients. La plupart de nos clients utilisent une composition similaire. 

En fonction de la documentation que vous produisez et pour qui, vous devrez savoir quelles formes peut prendre votre documentation. Jacob Kaplan-Moss en parle en détail dans What to write. Il explique comment les tutoriels, les guides thématiques et le matériel de référence constituent l'essentiel de la documentation dans la plupart des cas : 

  • Tutoriels : Les tutoriels sont la forme la plus élémentaire de documentation. Pour notre documentation destinée aux clients, les tutoriels sont nos ressources pratiques que nos utilisateurs utilisent pour ajouter une base de connaissances à leur site web avec notre plugin ou pour l'alimenter avec des articles. 
  • Guides thématiques : Les guides thématiques vont généralement beaucoup plus loin que les tutoriels et traitent de sujets plus spécialisés. En ce qui nous concerne, il s'agit de nos guides sur des sujets tels que la traduction et les intégrations. Nous les classons vaguement dans la catégorie des sujets avancés.
  • Référence : Dans le contexte de notre documentation destinée aux clients, ce type de document contient des informations sur nos intégrations avec nos partenaires que nos utilisateurs pourraient trouver utiles lors de la mise en place de leurs intégrations. Ou des liens vers des éléments qu'ils pourraient trouver utiles lors de la mise en œuvre de l'une de nos solutions HeroThemes .

Commencer par un fichier README (et s'en inspirer)

Maintenant que tout est clair, vous êtes prêt à passer à la partie rédactionnelle. La partie rédactionnelle de la documentation commence par un fichier README. Considérez-le comme la page de couverture ou le plan de votre documentation. 

Si vous travaillez sur la documentation de votre logiciel que vos collègues (développeurs/testateurs/optimiseurs) utiliseront, votre fichier README aura une certaine apparence. 

Exemple de fichier README

Et si vous rédigez de la documentation destinée aux clients, vous voudrez peut-être l'adapter pour qu'elle ait du sens pour le public visé et le travail qu'il doit accomplir. Le contenu, quant à lui, reste plus ou moins le même. Ci-dessous, vous pouvez voir comment un article d'assistance expliquant le fonctionnement d'une intégration commence par une page de couverture qui lui est propre.

Exemple de documentation

Il ne vous reste plus qu'à prendre votre fichier READMe ou le plan de votre documentation et à le remplir une section à la fois. Voici quelques ressources tirées de notre blog pour vous aider à remplir votre documentation :

Une fois cette étape franchie, n'oubliez pas d'ajouter une partie consacrée à la révision et au test.

La révision est un élément essentiel du processus de documentation. Elle vous permet de vous assurer que votre documentation fonctionne réellement.

Dans son processus de révision de la documentation en cinq étapes, Tom Johnson, rédacteur technique, indique que la première étape est incontournable : vous - le rédacteur de la documentation - faites "fonctionner le produit" pour vous-même en suivant les étapes que vous avez écrites.

Définir un calendrier de mise à jour

La documentation commence à se périmer dès qu'elle est publiée. Il faut donc prévoir un calendrier de mise à jour.

La fréquence des mises à jour dépend de la documentation que vous consultez. Par exemple, la documentation destinée à l'utilisateur n'aura besoin d'être mise à jour que lorsque vous mettrez votre produit à jour.

La documentation destinée aux développeurs - la documentation du code technique - est toujours en cours (documentation en ligne).

Votre documentation de travail interne, quant à elle, pourrait être mise à jour à chaque fois que quelque chose change - par exemple, lorsque vous remplacez votre outil de gestion de projet actuel ou même lorsque vous découvrez simplement une manière plus optimisée d'effectuer un certain travail. La capture des connaissances tribales et la capture des connaissances générales sont quelques-uns des exercices en cours dans ce type de documentation.

Lorsque cela se justifie, maintenez un journal des modifications dans votre documentation afin que les utilisateurs ne se sentent pas perdus lorsqu'ils voient une version mise à jour.

En outre, dans le cadre de la mise à jour de votre documentation, débarrassez-vous des fichiers obsolètes et des doublons. Une recherche dans votre documentation ne devrait jamais renvoyer plusieurs versions du même contenu d'assistance. Chaque sujet ne devrait nécessiter qu'une seule ressource. 

Pour conclure...

Une fois que vous avez adapté ce guide général sur la rédaction de la documentation à votre flux de travail, documentez votre processus de rédaction de la documentation.

Cela vous aidera non seulement à normaliser la rédaction de votre documentation, mais aussi à permettre à d'autres de s'en inspirer, car la documentation est toujours en cours.

À vous de jouer... Comment abordez-vous la rédaction de la documentation ?

Laisser un commentaire ?