Documentation technique : Github ou WordPress ?

changelogJe passe une partie significative de mon temps à rédiger de la documentation technique, souvent sous forme de tutoriels ou HOWTOs. Cette documentation, je l’écris en premier lieu pour moi-même. Lorsque j’arrive à résoudre un problème technique un peu plus pointu (configurer l’authentification centralisée, filtrer les réseaux sociaux avec le pare-feu, faire fonctionner une carte wifi récalcitrante, etc.) je prends le temps de noter comment je m’y suis pris, pas à pas. Il est peu probable que je me rappelle tous les détails de l’opération si jamais je dois la refaire six mois plus tard.

Publier sa propre documentation, c’est aussi un gage de qualité. D’autres que moi pourront s’en servir, et si jamais quelque chose n’est pas clair ou s’il y a une erreur, je le saurai probablement assez vite.

J’ai longtemps hésité entre deux formats, qui ont chacun leurs avantages et leurs inconvénients :

  • les HOWTOs au format texte simple, stockés sur Github et publiés sur le Web
  • les pages et les articles publiés dans un blog WordPress comme celui-ci

L’avantage du HOWTO au format texte simple, c’est que ça peut se lire partout, notamment sur un serveur dépourvu d’environnement graphique. Il suffit d’ouvrir une deuxième console pour importer la documentation avec un coup de git clone, à moins qu’on ne l’affiche directement avec un navigateur Web en mode texte comme Links ou Lynx.

Le format texte est également le plus pérenne, pour des raisons plus ou moins évidentes. Il ne dépend pas d’un moteur de blog, et il n’a besoin ni d’une base de données MySQL ni de PHP. Tout ce qu’il faut, c’est un éditeur de texte simple comme Vim et un visualiseur comme less. Pour illustrer mon propos, voici par exemple les instructions pour installer Slackware 1.01. Cette petite documentation date de 1993. Elle a donc vingt-deux ans. Je n’ose pas imaginer ce que sera devenu le contenu de ce blog en l’an 2037.

L’avantage d’un blog comme celui-ci, c’est que c’est certainement plus joli à voir. On peut choisir entre différents gabarits, on dispose de toute une panoplie d’outils de mise en forme, on peut insérer des images, etc. Un blog permet également d’interagir avec d’autres, de publier leurs remarques éventuelles et d’y répondre. Malheureusement, depuis quelque temps, les blogs comme celui-ci semblent constituer une cible privilégiée pour des attaques malveillantes. Les vulnérabilités diverses et variées d’un moteur de blog comme WordPress sont susceptibles de mettre mes données en péril.

J’ai donc décidé d’opter pour un mélange des deux formats. Désormais, je ne publierai plus que des articles relativement brefs sur ce blog, en renvoyant vers un HOWTO au format texte dès que ça devient plus technique. Voici à quoi cela ressemble dorénavant.

Amis lecteurs de ce blog, je vous demande un petit peu de patience en attendant de transférer les articles techniques écrits jusqu’ici vers le nouveau format.

Publicités
Cet article, publié dans Linux, est tagué , , , . Ajoutez ce permalien à vos favoris.

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s