Il existe autant de manière d’écrire de la documentation que de développeurs et d’entreprises.

La comm’ c’est la vie

La communication est la clé de tout projet, une documentation que l’on a envie de lire permet de fluidifier les échanges et d’augmenter la productivité et la fiabilité.

À l’inverse une mauvaise documentation va entrainer des frictions, des réunions à rallonge, des incompréhensions qui sont néfastes pour le projet.

On peut mesurer l’impact d’une bonne documentation via une absence de friction et globalement une bonne compréhension des enjeux par les développeurs et l’équipe de projet.

Voici 8 recommandations pour rédiger une documentation impactante et efficace !

Mes documentations ont toujours été saluées par les développeurs et par mes clients au fil des années. Ici je vous livre tout mes secrets 🔓

1. Ne rien présupposer sur le lecteur ️🤌

Le développeur qui lira votre documentation n’a peut-être aucune culture numérique, du moins considérez qu’il n’en a aucune et partez du principe qu’il ne sait pas où il est, ce qu’il doit faire et qu’il n’a pas de bagage technique a part lire et naviguer sur votre documentation.

Partez du principe que la personne qui lit votre doc est **NULLE **comme vous l’étiez avant.

Ce sera d’autant plus simple d’intégrer une nouvelle recrue à votre équipe en partant de ce principe.

Partez from scratch, si c’est une documentation pour lancer un projet, imaginez que le développeur n’a rien d’installé sur son ordinateur et qu’il doit partir de zéro.

🔗 Faire des liens

Une documentation doit être concise et guider le lecteur depuis zéro comme on a pu le voir précédemment. Mais cela devient un travail de titan, pas du tout synthétique si l’on doit ré-expliquer tout depuis zéro.

Il convient alors de faire des liens pour hiérarchiser l’information. Time to read my friends

☝️ Exemple

Je rédige une documentation pour lancer une application PHP avec un framework.

Je respecte le principe que le développeur n’a rien installé sur son ordinateur et qu’il ne connait pas le framework en question.

• Comment installer PHP ?
• Comment fonctionne le framework ?
• Et comment l’installer ?

Dans ce cas, il faut simplement renvoyer vers la documentation du langage (php.net), du framework(laravel.com) en question OU vers une documentation claire si la documentation officielle est peu ou pas claire.

Le renvoi vers des documentations externe doit être un reflexe, si les documentations en questions sont de qualité !

Les liens permettent non seulement de vous éviter de ré-écrire ce qui a déjà été fait par d’autres personnes, et probablement mieux que vous dans le temps imparti. Mais aussi de montrer aux développeurs / lecteurs que le net regorge de documentations de qualité qu’il est possible d’exploiter.

💡 On apporte alors au développeur** de la culture numérique**.

On lui donne des ressources utile pour le future dans le cas  où il pourrait rencontrer un problème sur le langage / framework / concept en question.

🎯 Aller à l’essentiel

Une documentation doit répondre à une problématique, elle doit conduire à la résolution d’un obstacle sur le chemin du développeur.

Il faut donc aller à l’essentiel que ce soit dans les titres, dans le contenu et dans la manière de résoudre le problème.

⚠️ On ne peut pas écrire de documentation lorsque l’on à pas compris comment fonctionne le système ou l’outil que l’on souhaite documenter.

💁‍♂️ Faire appel à des débutants

C’est contre-intuitif mais pour faire une bonne documentation il faut avoir un débutant sous la main ou être sois même un débutant.

Vous pourrez écrire une bonne documentation que si vous répondez aux problèmes qui surviennent pour un débutant (installation d’un projet, mise en place d’un framework, utilisation de ressource de l’entreprise, etc.). Wait, Wat.

Cela demande beaucoup d’empathie cognitive et de noter absolument tout les points de friction qui sont apparu lors de la résolution du problème.

Illustrer votre documentation

Personne n’a envie de lire de gros blocs de texte sans mise en forme, tout comme un développeur à besoin d’aller à l’essentiel.

Dans ce cas : Il faut illustrer !

• Via des schémas
• Des images
• Des memes pour détendre la lecture et faire passer des messages
• Des vidéos (courtes de préférences)
• Des émojis pour égayer et marquer des points importants

Et puis la documentation n’a pas à être triste ! On peut aussi aimer la lire parce qu’elle est drôle par moment :)

🎨 La mise en forme

Nous incluons dans la documentation l’utilisation de la mise en forme.

C’est un point souvent négligé car beaucoup de personnes n’aiment pas rédiger de la documentation et donc font l’impasse sur les finitions visuelles pour aller plus vite.

⚠️ Ne faites pas l’impasse sur la mise en forme ! JAMAIS

Si votre documentation n’est pas visuellement structurée et claire, personne ne l’a lira et vous aurez effectivement travaillé pour rien.

Utilisez le markdown pour les documentations de développement. Les outils markdown incluent des moyens d’ajouter de la coloration syntaxique pour des zones de code.

Plus d’informations avec la Cheat Sheet Markdown

🧑‍💻 Du code

Par exemple :

Syntaxe pour écrire du code et l’afficher clairement

    fun printSum(a: Int, b: Int): Unit {
        println("sum of $a and $b is ${a + b}")
    }

C’est quand meme plus sympa que le présenter comme ceci : fun printSum(a: Int, b: Int): Unit { println(“sum of $a and $b is ${a + b}”) }

Pour les listes également

Exemple d’une checklist de démarrage pour une application Laravel Avec la syntaxe * [ ] Item

Avoir une hiérarchie cohérente

La hiérarchisation des informations est essentielle, il faut savoir ranger les différents niveaux d’informations et présenter graduellement les notions afin de ne pas perdre un débutant tout en répondant aux besoins d’une personne plus avancée.

Pour cela on tente de savamment doser la rédaction descriptive et la narration.

• 👁 Descriptive : Ici on va lister ce qu’il est possible de faire avec le système ou l’outil à aborder

• Exemple : une documentation des différentes fonctions de l’API

• 🎯 Narrative : plutot comme un tutoriel, où l’on souhaite emmener le lecteur quelque part pour qu’il comprenne comment le système fonctionne de manière guidé et ne pas le perdre.

• Exemple : une section “Getting Started” qui va nous guider jusqu’à un “Hello World” fonctionnel

🧰 Les outils

Les outils sont secondaires, ce qui compte c’est bien la rédaction, la mise en forme et l’accessibilité.

Votre documentation doit être accessible facilement et avoir un moteur de recherche dans l’idéal.

Les critères principaux pour choisir un outil de documentation sont :

• Le partage / accessibilité par une équipe
• La capacité de mise en forme (supporte les balises de code et la syntaxe markdown basique)
• La facilité de déploiement et de mise à jour

VuePress, Hugo, Astro, etc.

VuePress permet de rédiger une documentation visuellement très agréable, avec une structuration en Markdown, ce qui rend l’outil propice aux documentation de développement.

VuePress inclus par défaut un moteur de recherche en local qui fait très bien le boulot et peut être synchroniser avec Git pour versionner la documentation.

• Exemple : https://vuepress.vuejs.org/
• Exemple : Le site que vous êtes en train de lire est fait avec Astro, un outil similaire à VuePress

Une bonne solution, mais pas simple à prendre en main pour un débutant ou un non développeur

GitHub, Gitlab, Bitbucket Wiki

Chaque outil de gestion du code source connu possède son propre outil de Wiki intégré au dépôt d’un projet.

Ainsi vous pouvez facilement créer des pages, et faire une structure de documentation.

A noter que le wiki est propre à un projet pour Gitlab, ce qui fait que l’accessibilité de la documentation est limité. Si le développeur ne va pas fouiller le projet il ne trouvera pas le Wiki.

Notre recommandation est d’avoir un point d’accès centralisé qui liste les différents wikis disponibles.

Github Page / Gitlab Page

Pour une documentation plutôt orienté externe, Github ou Gitlab permettent de compiler le contenu Markdown d’un dépôt et de le servir sous forme de site web statique.

Ce genre de site ne possède pas de moteur de recherche.

Plutôt simple à mettre en place mais assez limité.

Outline / Notions / Gitbook

Des outils de documentation très bien ficelé et avec une hiérarchie claire.

Cela permet de tout centraliser et de servir de la documentation interne ou externe avec un fort pouvoir d’édition. C’est à dire que l’on peut éditer la documentation sans être un développeur, le Markdown est supporté mais une interface graphique permet de se passer du savoir faire d’un développeur.

Une personne connaissant Word peut s’en servir sans problème.

Bases de connaissances type Zendesk

Les bases de connaissances sont intéressantes en équipe interne même si elles sont, la plupart du temps, utilisées pour une documentation publique / client.

Exemple : https://help.twitter.com/en

Cela permet d’avoir un format type FAQ avec un moteur de recherche et des articles orienté “Réponse”

Voilà

L’objectif de ce post est d’avoir un premier aperçu des bonnes pratiques, il n’est en rien un condensé de “règles” à appliquer, mais plutôt des exemples de ce qui fonctionne bien.

Il faut bien comprendre que ce n’est pas simple d’écrire une bonne documentation et que cela prend plusieurs itérations, avec des feedbacks de la part de l’équipe, des clients ou des décideurs en interne pour avoir quelque chose de cohérent, utile et agréable à utiliser.