La documentation d’un projet, quel que soit son domaine, est une chose primordiale. Par expérience, nous savons qu’elle est souvent mise de côté car les équipes manquent de temps, n’ont pas les bons outils, ou les membres de celles-ci ne sont souvent pas sensibilisés à son importance.
Et pourtant la documentation (surtout technique) peut s’avérer d’une aide particulièrement précieuse dans de nombreuses situations :
- Reprise d’un projet poussiéreux après des mois ou des années de stand-by
- Changement d’équipe
- Migration ou maintenance technique d’un projet
Le but de cet article est de vous introduire à la collaboration du versioning avec Git et de la syntaxe Markdown afin de vous permettre de mieux gérer vos documentations.
La syntaxe Markdown
La syntaxe Markdown est un langage de balisage léger. Son but est d’offrir une syntaxe facile à lire et à écrire, et de le formater sans perturber la rédaction.
Il est utilisé couramment dans le milieu du développement informatique et en particulier de l’open-source car il est courant d’associer un fichier README et de LICENCE à ses projets, à savoir deux fichiers explicatifs rédigés en Markdown. Github affiche par exemple le fichier README interprété directement sur la page d’accueil de chaque projet (idem pour Stash, Gitlab, etc).
Ce qui est appréciable avec le Markdown c’est qu’on ne parasite pas son texte avec des balises HTML : c’est au moment de l’affichage qu’on va interpréter le balisage et le transformer en HTML. Il devient alors facile pour n’importe qui de rédiger des textes formatés pour le Web sans connaissance de la technique. Il existe un nombre important d’éditeurs Markdown assez agréables à utiliser (Byword sur Mac/iPhone/iPad pour ne citer que lui), même si on peut évidemment écrire du Markdown dans n’importe quel éditeur de texte.
Quelques exemples de la simplicité de la syntaxe Markdown :
– Du **texte en gras** avec les doubles-étoiles
– Du *texte en italique* avec une étoile unique
– Sont gérés aussi les titres, sous titres, liens, images, séparateurs horizontaux, etc…
Vous trouverez ici une documentation (en anglais).
Le versioning avec Git
Si vous êtes un développeur alors nous ne vous apprenons rien : Git, au même titre que SVN, est un outil de versioning.
Pour les néophytes : c’est un outil qui permet de publier des ressources informatiques (en général du code source) sur un ou plusieurs serveurs centraux (ou du moins entre plusieurs machines) et de travailler de façon collaborative sur le même projet, voir sur les mêmes fichiers, en même temps.
Généralement utilisé par les équipes techniques pour partager le code source des projets, Git a plusieurs intérêts : le code synchronisé sur un serveur central réduit les risques de perte, il est possible de savoir qui a modifié quoi et quand, et surtout les ressources sont versionnées, c’est à dire qu’il est possible de revenir en arrière après chaque modification.
Git est très adapté pour le texte et donc pour le code source et les documentations.
Mise en situation
Plusieurs mises en situation sont possibles. La première est d’utiliser un dépôt Git classique afin d’y héberger uniquement la documentation. L’avantage est de pouvoir accéder à la documentation d’un projet sans avoir à récupérer tout son contenu (utile lorsque le projet est particulièrement lourd).
La seconde option est d’associer la documentation au dépôt Git du projet associé. On peut par exemple imaginer de mettre tous les fichiers Markdown dans un dossier doc à la racine et qu’un lien sur le fichier README du projet pointerait directement sur celle-ci.
Une dernière possibilité est d’utiliser un outil de gestionnaire de code comme Gitlab qui créé automatiquement un dépôt git de wiki compatible Markdown pour chaque projet créé. L’avantage c’est qu’il est alors possible d’accéder à la documentation du projet simplement en se rendant dans l’interface graphique du projet sur la plateforme.
Conclusion
Permettre à une équipe technique (ou non) de documenter ses projets est essentiel pour la pérénité de ceux-ci. Trop souvent les membres des équipes sont confrontés à des reprises de projets à propos desquels personne ne sait rien : comment on les installe, où sont les accès serveurs, quelles sont les dernières discussions avec les clients, qui a travaillé dessus, etc.
Prendre 5 minutes pour rédiger une documentation, c’est gagner potentiellement des heures quelques mois ou années plus tard. L’association du Markdown et de Git facilite la rédaction et la publication des documentations pour un travail en équipe.
