Mes outils favoris
Markdown, Docusaurus & Schémas — Mon trio gagnant pour la documentation
Il y a quelque temps, quelqu’un m’a demandé quel outil j’utilisais pour la documentation technique — et au lieu d’en choisir un seul, j’ai réalisé que ma configuration est plutôt un trio créatif.
J’écris en Markdown, je construis avec Docusaurus, et je dessine avec Excalidraw. Dans cet article, je partage pourquoi cette combinaison fonctionne si bien pour moi et comment elle rend l’écriture à la fois simple et puissante.
🟢 On m’a demandé il y a quelques mois quel était mon outil préféré pour la documentation technique. Voici ma réponse.
Ma configuration d’écriture préférée n’est pas un outil unique – c’est une combinaison d’un langage (Markdown) et d’un générateur de site statique (actuellement, Docusaurus).
Markdown
⭐ https://www.markdownguide.org/
J’ai utilisé RoboHelp pendant un certain temps, un outil de rédaction d’aide bien connu. Je l’aimais pour sa capacité à générer des systèmes d’aide autonomes ainsi que de l’aide en ligne, et pour la possibilité de visualiser et modifier le code source HTML.
J’ai commencé avec HTML en 1998, en écrivant les balises dans Notepad, en les reliant à une feuille de style CSS externe, puis en lançant le fichier index.html. J’aimais cette simplicité et la possibilité de transférer ses compétences vers la compréhension du logiciel et de la technologie, la structuration du contenu, et la concentration sur l’écriture plutôt que sur l’outil.
Aujourd’hui, j’écris en Markdown et j’utilise un SSG pour générer le HTML.
Markdown n’est, par définition, pas un langage de balisage. Cela signifie que :
- vous ne perdez pas de temps à intégrer des informations de style dans le fichier de contenu
- contrairement aux outils avec interface graphique, vous n’avez pas à cliquer partout pour appliquer un style à chaque groupe de mots ou pour créer une feuille de style
Avec Markdown, créer un titre de niveau 2 est aussi simple et rapide que d’appuyer deux fois sur la touche #. Ajouter une note est aussi rapide qu’un appui 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 SSG comme Hugo, Docusaurus, Jekyll, Middleman, etc. utilisent Markdown.
Et surtout, les développeurs connaissent bien Markdown (grâce à GitHub/GitLab). C’est un excellent point si vous voulez qu’ils contribuent à la documentation de l’entreprise ou simplement relisent 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 de documentation.
Docusaurus est un projet développé par l’équipe Meta Open Source, avec une communauté très active.
Il est logique pour moi que mon outil préféré soit open source : pas de licence, une communauté forte 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é (contrairement à certains outils propriétaires qui les hébergent sur leurs propres serveurs).
Docusaurus permet de construire rapidement un site de documentation et offre une large gamme de fonctionnalités de structuration et de style. Il est facile à personnaliser et à enrichir, pour que votre site ne ressemble pas aux autres mais reflète l’image de votre entreprise.
Vous pouvez vous inspirer des plus de 300 sites différents présentés dans la page Showcase.
La documentation de Docusaurus est très complète, et vous pouvez démarrer facilement si vous êtes familier avec le docs-as-code* et que vous n’avez pas peur d’aller “sous le capot”.
Docusaurus est un outil de rédaction qui vous permet de vous concentrer sur votre contenu : les pages, l’architecture du site, la navigation.
Tout le travail sur les fichiers de structure, la sidebar, le CSS et le contenu se 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, et bien plus encore grâce aux plugins développés par la communauté Docusaurus.
* Docs-as-code est une approche documentaire où le contenu technique est rédigé, relu et publié avec les mêmes outils et workflows que ceux utilisés pour le développement logiciel.
Excalidraw
Pour être exhaustive, je complète ces outils avec un tableau blanc virtuel (open source) nommé Excalidraw pour créer des schémas. Car il est souvent plus efficace d’expliquer avec des schémas qu’avec des mots.
Excalidraw est un tableau blanc virtuel qui permet de créer des schémas avec une esthétique agréable et dessinée à la main — comme s’ils avaient été esquissés sur un paperboard avec un feutre.
À partir d’une bibliothèque d’outils simples (formes, flèches, lignes, texte, couleurs), vous pouvez dessiner tout ce que vous voulez avec un style naturel et esquissé.
C’est utile, que vous schématisiez un flux technique, que vous fassiez du brainstorming ou que vous illustriez un concept.