Markdown et auto-documentation
S’il y a bien un concept que je n'ai vu être développé nul part à propos du Markdown c'est bien celui de l'auto-documentation. On comprend qu'il soit possible de créer de la documentation avec un corpus composé de fichiers Markdown ; mais on oublie que celui-ci permet aussi de rédiger de l'auto-documentation.
Qu’est-ce que l’auto-documentation ?
On trouve très peu de ressources concernant l’auto-documentation. Je mets personnellement le principe de génération de documentation automatisée de côté, pour me concentrer sur le principe de documenter personnellement ses pratiques professionnelles ou non.
Le but est de pouvoir se rappeler comment une chose a été réalisée (prendre des notes), afin de le reproduire plus facilement par la suite ou encore de laisser une trace pour des personnes qui auront à reproduire des tâches identiques par la suite.
Rien de nouveau dans cette activité car nous la pratiquons au quotidien de manière plus ou moins aboutie :
- Prendre des notes (ex: réunion)
- Noter un processus (ex: cuisine)
- Dessiner (ex: jardinage)
- Prendre une série de photos (ex: voyage)
L’auto-documentation à l’ère du numérique
L’auto-documentation sert à conserver de la mémoire (individuelle ou collective) sur un support physique. Les souvenirs peuvent être stockés dans votre mémoire humaine, mais étant donnée sa faillibilité ; les humains ont décidé de conserver une partie de leurs souvenirs sur des supports matériels : pierre (ex: arc de triomphe), papier (ex: livres), disques durs (ex : facebook)…
Avant l’ère industrielle, les livres et autre supports de mémoire écrits existaient mais ils étaient réservés à une classe de la population qui savait les décoder ; cela servait à des pratiques bien particulières comme le droit. La majeure partie des autres personnes, qui vivaient dans la subsistance, se transmettaient leur savoir de manière orale et à travers la reproduction de gestes et techniques manuelles.
De nos jours, on considère que la lecture et l’écriture sont des prérequis à la vie en société, que c’est essentiel pour l’échange et la communication. Notons que l’invention et l’usage du support numérique couplé aux possibilités d’échange permis par Internet et le Web changent complétement la donne en terme de relation entre les humains et les groupes humains.
Il est désormais possible, une fois équipé d’un périphérique adapté, de documenter facilement un grand ensemble de nos pratiques. C’est d’ailleurs ainsi que le web à prospéré, grâce aux tutoriaux et fora permettant d’adopter une pratique autodidacte pour réaliser certaines de nos envies.
Markdown et auto-documentation ?
Rappellons le encore une fois, un générateur de site statique est un script qui prend des fichiers en entrée et les convertis en d’autres fichiers. Le processus le plus utilisé est celui de convertir des fichiers Markdown (.md) en fichier HTML (.html).
Le Markdown est l’une des manière le plus simple d’écrire du contenu sémantisé ; la sémantisation est indipensable pour structurer une document. Sur ce blog nous parlons des avantages du Markdown pour la réalisation éventuelle des sites ambitieux et volumineux. Cependant, n’oublions pas que le plus simple des blogs ou la plus simple des documentations peut être écrit en Markdown (ex: README.md de jamstatic.fr)
Vous pouvez de la manière la plus simple qu’il soit, écrire, grâce à un logiciel approprié, vos notes en Markdown. C’est-à-dire écrire votre documentation personnelle grâce à un logiciel de notes qui prend en compte le Markdown. En gros vous auto-documenter en écrivant en Markdown. Voire même, auto-documenter à plusieurs un travail collectif en partageant des notes écrites en Markdown.
Imaginons maintenant que vous rédigiez tout au format Markdown. Bien évidemment, vous pourriez publier et partager ces notes sur un site web avec un simple script d’export automatique (un truc qu’on appellerait générateur de site statique).
Conclusion
Les modalités assumées de notre monde professionnel actuel sont basées sur de la création permanente, continue et rapide. La création nécessite une grande connaissance de ce qui existe déjà (veille), un partage pour un travail collaboratif (action) et une politique de conservation des pratiques (savoir).
Le format Markdown propose donc 2 avantages : celui de pouvoir se conserver et se transporter facilement mais aussi de pouvoir être un dénominateur commun d’une pratique générale d’écriture, donc de documentation.
Imaginons une organisation où l’ensemble des collaborateurs utiliserait le Markdown pour l’écriture d’un grand ensemble de ses documents ; cette organisation aurait le bénéfice de pouvoir stocker à peu de frais tout son savoir, d’uniformiser les pratiques d’écriture (ce qui facilite l’intégration de nouveaux membres) et, enfin, de pouvoir manipuler ces données uniformes à sa guide pour de la publication multi-supports.