Il y a quelques mois, on m’a demandé quel était mon outil préféré pour la documentation technique. Voici ma réponse.
Mon outil de création préféré n’est pas un outil unique mais la combinaison d’un langage (Markdown) et d’un générateur de site statique (il s’agit de Docusaurus).
Markdown
⭐ https://www.markdownguide.org/
J’ai utilisé RoboHelp à une époque, qui était un outil de création d’aide bien connu. Je l’aimais parce qu’il permettait de générer des systèmes d’aide autonomes ainsi que de l’aide Web, et qu’il permettait de visualiser et de modifier le code source HTML.
J’ai commencé avec le HTML en 1998, en écrivant les balises dans le bloc-notes, en les liant à un CSS externe, puis en exécutant le fichier index.html. J’ai adoré cette simplicité et la possibilité de transférer ses compétences pour comprendre le logiciel et la technologie, structurer le contenu et se concentrer sur l’écriture, au lieu d’utiliser l’outil de création.
Maintenant, j’écris en Markdown et j’utilise un SSG pour générer le HTML.
Le format Markdown n’est, par définition, pas un langage de balisage. Cela signifie que vous ne passez pas de temps à intégrer des informations de style dans le fichier de contenu. Cela signifie que, à la différence des outils de création avec interface graphique, vous n’avez pas à cliquer ici et là pour appliquer un style à chaque groupe de mots ou à cliquer ici et là pour créer la feuille de style. Avec Markdown, créer un titre 2 est aussi simple et rapide que d’appuyer deux fois sur la touche dièse. L’ajout d’une note est aussi rapide que d’appuyer sur la touche >.
Markdown est un langage de structuration de contenu. Grâce à sa simplicité, la structure de votre contenu apparaît avec clarté et soutient votre réflexion lorsque vous documentez une fonctionnalité ou expliquez un concept technique.
Markdown est utilisé par de nombreux projets, plateformes et frameworks. Les fichiers Readme sur GitHub ou GitLab sont en Markdown. Les GSS comme Hugo, Docusaurus, Jekyll, Middleman, etc. utilisent Markdown. Enfin, les développeurs connaissent bien le format Markdown (grâce à GitHub/GitLab). C’est un très bon point lorsque vous souhaitez qu’ils contribuent à la documentation de l’entreprise ou qu’ils corrigent simplement vos pages directement sur Git.
Docusaurus
Comme je l’ai mentionné au début de ce texte, j’utilise Docusaurus pour générer mes sites web de documentation.
Docusaurus est un projet développé par l’équipe Meta Open Source qui dispose d’une forte communauté.
Il est logique pour moi que mon outil préféré soit open source : pas de licences, une forte communauté qui s’entraide avec des plugins, des réponses, des suggestions de fonctionnalités, et plus encore. Les sources sont stockées de votre côté (à la différence de certains outils propriétaires qui stockent vos sources sur leurs propres serveurs).
Docusaurus permet de créer rapidement un site Web de documentation et dispose d’un large éventail de fonctions de structuration et de style. Il est facile à personnaliser et à enrichir, de sorte que votre site ne sera pas identique aux autres mais reflétera l’image de votre entreprise.
Vous pouvez vous inspirer de plus de 300 sites web différents sur la page d’exposition.
La documentation de Docusaurus est très complète, et vous pouvez commencer à l’utiliser facilement si vous êtes familier avec les docs-as-code et si vous n’avez pas peur d’aborder les choses depuis les coulisses.
Docusaurus est un outil de création qui vous permet de vous concentrer sur votre contenu : les pages de contenu, l’architecture du site Web et la navigation. Tout le travail sur les fichiers de structure, la barre latérale, les CSS, et le contenu est fait dans votre propre éditeur de code (Visual Studio Code dans mon cas). Docusaurus interagit avec GitHub ou GitLab.
Vous pouvez ajouter un moteur de recherche, localiser votre site dans de nombreuses langues, et bien plus encore grâce aux plugins développés par la communauté Docusaurus.
Excalidraw
Pour être exhaustif, je complète ces outils par un tableau blanc virtuel (open source) nommé Excalidraw pour créer des diagrammes. Parce que vous avez souvent besoin d’expliquer des choses avec des dessins plutôt qu’avec des mots.
