Savoir rédiger une bonne documentation, qu'elle soit technique ou destinée aux utilisateurs, consiste à produire un document clair, précis et utile. Il doit expliquer de façon simple et compréhensible comment utiliser un produit ou un service, tout en apportant suffisamment de détails pour que les lecteurs comprennent ses fonctionnalités et ses avantages.
Une bonne documentation doit être lisible, structurée de manière logique et permettre de trouver rapidement l'information recherchée. C'est un outil essentiel pour aider les utilisateurs à tirer le meilleur parti d'un produit et pour favoriser leur satisfaction sur le long terme.
Il existe plusieurs types de documentation, chacun avec ses objectifs. Les documentations techniques expliquent le fonctionnement interne d'un produit, tandis que les documentations utilisateur décrivent l'installation, la configuration et l'utilisation. La plupart des autres formats se rattachent à l'une de ces deux grandes catégories.
Je préfère la documentation technique, que je trouve plus intéressante à rédiger. Elle a l'avantage d'être souvent concise et peut, dans certains cas, se présenter sous forme de listes d'instructions claires, accompagnées d'explications techniques à chaque étape. Ce format me convient particulièrement.
La documentation utilisateur doit être accessible à un public plus large et est souvent plus descriptive. Là où une documentation technique peut se permettre la concision, la documentation utilisateur nécessite des phrases complètes et des explications détaillées pour que tous les utilisateurs comprennent les fonctionnalités et les bénéfices.
Ce n'est pas forcément plus complexe, mais le style est différent, c'est de la rédaction plus conventionnelle, moins alignée avec mes habitudes. La documentation utilisateur nécessite souvent davantage d'illustrations (captures d'écran, vidéos), ce qui rallonge le travail, alors que la documentation technique peut souvent se contenter de texte, de code ou de schémas générés en texte (par exemple avec Mermaid).
J'ai commencé à rédiger des documentations en mars 2023, lors de mon premier stage en entreprise chez Extrait d'Anjou, une société spécialisée dans les extraits de plantes. Le service informatique était assuré par une seule personne, qui s'occupait des postes, des serveurs de production et des logiciels. Il m'a beaucoup appris durant ce stage.
Parmi ses enseignements, il m'a montré la documentation qu'il avait rédigée en Markdown. Elle permet au prochain informaticien de comprendre rapidement l'infrastructure, la configuration des serveurs et les logiciels utilisés.
En découvrant cette documentation, j'ai réalisé l'importance qu'avait une bonne documentation. Le Markdown présente de nombreux avantages : simplicité, facilité de partage et de modification, et possibilité de conversion vers d'autres formats (HTML, PDF, etc.), ce qui en fait un format très polyvalent et complet pour la documentation.
Grâce à des extensions comme Mermaid, il est possible de produire des schémas d'architecture, des diagrammes de classes ou de séquence uniquement en texte. C'est notamment ainsi que j'ai réalisé le schéma de mon parcours.
Suite à cette découverte, j'ai commencé Ma Documentation technique en juin 2023, elle aussi entièrement rédigée en Markdown. Elle a beaucoup évolué : d'un fichier initial, le projet est passé à plusieurs fichiers organisés en dossiers. J'ai ensuite créé un dépôt GitHub pour y accéder partout, puis utilisé GitHub Pages pour la publier en ligne avec une interface plus agréable et une meilleure organisation.
Aujourd'hui, Ma Documentation est toujours écrite en Markdown mais publiée avec MkDocs. À partir des fichiers Markdown, MkDocs génère un site HTML/CSS statique offrant une recherche intégrée et un thème clair/sombre. Les fichiers générés sont hébergés sur GitHub Pages et sont aussi servis via un conteneur Docker sur mon serveur de production. L'objectif de cette double publication est de lier mon nom de domaine à Ma Documentation pour la rendre facilement accessible et la faire figurer dans la liste automatisée de mes projets.
Ma Documentation couvre de nombreux sujets : configuration de serveurs, installation de logiciels, création d'une micro-entreprise en France, etc. Elle me sert de base de connaissances personnelle et d'aide-mémoire, afin de retrouver facilement des procédures éprouvées sans devoir tout réapprendre.
Elle me permet aussi de partager mes connaissances avec mes collègues ou des personnes de mon entourage. Je partage souvent des liens vers la documentation pour répondre rapidement à des questions, ce qui évite de répéter les mêmes explications et constitue un gain de temps pour tous.
Par exemple, après des recherches sur la création d'API avec NodeJS et la mise en pratique d'une architecture, j'ai rédigé une documentation technique complète avec explications, exemples de code et schémas d'architecture, disponible ici.
Cette documentation sur l'architecture d'API avec TypeScript est complète : création, comparaison et lancement de l'API, commandes, fichiers de configuration et exemples de code y figurent.
J'essaie de rendre mes documentations aussi complètes que possible. Lorsque je débutais, de nombreuses ressources omettaient les étapes préliminaires jugées évidentes, ce qui complique la compréhension des débutants. Je prends donc soin d'expliquer ces étapes pour faciliter l'apprentissage.
C'est notamment pour cela que j'ai rédigé une documentation complète pour créer une application web de zéro. Elle couvre la création d'une base PostgreSQL, la création d'une API avec NodeJS, le frontend avec Flutter et la mise en production avec Docker. Avec cette documentation et l'exemple d'Econoris, un développeur junior devrait pouvoir créer et déployer une application moderne sans avoir à chercher des informations dispersées.
J'ai rédigé de nombreuses documentations sur des sujets variés : clean code (10 bonnes pratiques), Java (parmi mes premiers travaux), TypeScript (très détaillé), création de paquets Debian, configuration de Visual Studio Code pour NodeJS/TypeScript, Git (aide-mémoire) et SSH (aide-mémoire pour l'installation et la configuration de serveurs).
Je continue de rédiger de nouvelles documentations quand j'apprends des sujets pour lesquels je ne trouve pas de ressources complètes. La limite principale est le temps. Maintenir et enrichir la documentation demande beaucoup d'efforts. J'essaie néanmoins de les garder à jour et aussi complètes que possible dès la rédaction initiale.
À l'origine, ces documents sont personnels. Même si je les partage, ils servent avant tout d'aide-mémoire personnel. Ils ne sont pas parfaits et peuvent contenir des fautes, mais les éléments techniques sont vérifiés et testés. Lorsque j'écris une documentation, c'est généralement après avoir réalisé et validé toutes les étapes décrites.
J'essaie aussi de référencer mes sources : vidéos, articles, documentations officielles, échanges avec des collègues ou parfois des résultats d'outils d'IA. Citer les sources permet au lecteur d'approfondir un sujet et d'identifier d'éventuelles variantes si une procédure ne fonctionne pas dans un contexte différent.
Bien que la majorité de mes documents soient techniques, j'ai aussi rédigé des documentations utilisateur, notamment pour Maven Lite. Maven Lite était destiné aux étudiants pour les aider à créer et développer des projets Java, il est donc essentiel que sa documentation soit claire et accessible aux débutants.
J'ai rédigé cette documentation en me mettant à la place d'un nouvel utilisateur qui découvre Maven Lite. Il va dabord se demander qu'est-ce que Maven Lite, à quoi sert-il et comment fonctionne-t-il ? J'ai donc commencé par présenter l'application, ses fonctionnalités et ses avantages.
Ensuite, une fois que l'utilisateur a compris ce qu'est Maven Lite, il va vouloir savoir comment l'installer. C'est pourquoi à la suite de l'introduction j'ai mis une section d'installation, qui explique comment installer Maven Lite sur les différents systèmes d'exploitation, avec des explications détaillées et toutes les commandes à utiliser.
Enfin, une section d'utilisation montre comment créer et développer des projets Java avec Maven Lite, accompagnée d'exemples de commandes et de code.
De plus, la commande "maven-lite --help" fournit une aide rapide sur les fonctionnalités principales et des exemples d'utilisation. Pour une référence complète, la page de manuel accessible via "man maven-lite" (sur Linux) détaille toutes les options avec de courtes explications.
Avoir plusieurs formats de documentation peut sembler redondant, mais ils sont complémentaires : la documentation en ligne est plus complète et destinée à la découverte, la page de manuel sert d'aide-mémoire et "--help" répond rapidement aux besoins ponctuels.
Les pages de manuel ("man maven-lite") servent d'aide-mémoire pour les utilisateurs familiers de l'outil qui recherchent une référence rapide, y compris pour des fonctionnalités avancées.
La commande "maven-lite --help" est pratique pour obtenir rapidement des exemples et des options de base sans consulter la documentation complète. Personnellement, je l'utilisais pour copier-coller les exemples de création de projet.
Ainsi, ces trois formats répondent à des besoins différents : découverte, référence et aide rapide. Il me semble important de proposer plusieurs types de documentation pour couvrir tous les usages.
La documentation est cruciale en développement. Je sais que mes documents ne sont pas parfaits : ils peuvent contenir des fautes et parfois manquer d'organisation, notamment parce que je les rédiges en parallèle du travail pratique. Malgré tout, le contenu technique est vérifié et fiable.
Malgré ces limites, la documentation reste une compétence que je maîtrise : je sais produire du contenu technique fiable. Il me suffit de relire pour améliorer la forme. Peu de développeurs aiment documenter, mais j'apprécie cet exercice car il me permet de partager mes connaissances et de valider ma compréhension des sujets.
Pour écrire une bonne documentation, il faut se mettre à la place du lecteur, se demander pourquoi il lit la page et adapter le contenu pour répondre à ses besoins.
Par exemple, si l'utilisateur cherche une réponse rapide, la documentation doit lui fournir l'information sans qu'il ait à fouiller l'ensemble des pages.
Pour un tutoriel (par exemple une installation), la documentation doit proposer une liste d'étapes simples, avec des explications claires pour que l'utilisateur suive le processus sans se perdre.
En se plaçant du point de vue du lecteur, on obtient déjà des documents plus efficaces et utiles, car ils répondent mieux aux besoins réels.
La documentation est un élément clé de réussite d'un projet. Les projets populaires disposent souvent d'une documentation solide, car elle facilite l'utilisation par les utilisateurs et la contribution par les développeurs.
Je compte continuer à produire de la documentation. J'aime cet exercice et c'est essentiel pour mes projets personnels comme professionnels. C'est une compétence importante que je développe continuellement.
Avec plus de temps, j'aimerais produire des documentations encore plus complètes : davantage d'exemples de code, des schémas d'architecture détaillés, et compléter certaines pages existantes (par exemple l'architecture frontend avec Flutter).
Je continuerai à progresser en m'inspirant de documentations de qualité et en utilisant des ressources libres. Je souhaite également produire davantage de documentations utilisateur, car elles sont essentielles pour l'adoption des projets.
