Woodgate.fr

Julien Ramel

Ingénieur Recherche & Développement, passionné par le Web et ses technologies. Responsable Technique de Wax Interactive Suisse. Lyonnais expatrié à Lausanne.


Documentez vos projets avec le combo Git/Markdown



La documentation d'un projet, quel que soit son domaine, est une chose primordiale. Par expérience, je sais 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 (turn-over important dans les sociétés techniques)
  • 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 que j'apprécie 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.

Cet article de blog est d'ailleurs lui-même rédigé en Markdown puisque j'utilise Ghost comme outil de blogging.

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 je ne vous apprends 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 avec Gitlab

À titre personnel j'ai mis en place une architecture pour gérer mes projets : j'héberge un outil nommé Gitlab sur un serveur dédié qui ne sert qu'à ça (ce n'est pas un serveur de trafic) et un second serveur dédié accueille le code source versioné (c'est le serveur de trafic, c'est à dire celui qui héberge les sites Web). Gitlab est un clone personnel de Github, il permet de gérer ses projets et d'héberger le code source de chacun chez-soi : il joue le rôle d'un serveur Git (même si ça n'existe pas à proprement parler). Il permet de travailler de façon collaborative, de ne donner accès qu'à certains projets, de faire du code review, etc.

Ce qui est intéressant avec Gitlab c'est que pour chaque projet créé l'outil génère automatiquement un second projet qui correspond au wiki du premier, avec un nombre illimité de pages possibles. Autrement dit : pour chaque projet créé, une documentation (vide) est générée. Et là où ça devient intéressant, c'est que le wiki en question est accessible via Git et interprété par la syntaxe GFM (GitLab Flavored Markdown, du Markdown un petit peu amélioré).

Dès lors, il est possible pour un développeur qui accède pour la première fois à un projet de trouver facilement sa documentation. Cela peut lui permettre d'obtenir des instructions d'installation, des accès aux serveurs (attention tout de même, il faut alors être sûr de la sécurité de son installation et ne surtout pas le faire pour un projet public), etc. À titre personnel, je documente l'installation de mes projets car j'associe souvent un nombre important de technologies et chacune à ses spécificités. Je sais qu'en cas de maintenance ou de réinstallation, je n'aurai pas deux fois à chercher la même information.

Il est évidemment possible de créer un repository Git à part entière pour sa documentation sans passer par le système de wiki de Gitlab, de l'associer au code source de son projet, ou encore d'utiliser SVN si vous vivez encore en 2010 ;-)

Conclusion

Permettre à une équipe technique (ou non) de documenter ses projets est essentiel pour la pérénité de ceux-ci. Trop souvent j'ai été confronté à des reprises de projets à propos desquels personne ne savait rien : comment on les installe, où sont les accès serveurs, quelles étaient 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.

N'hésitez pas à me suivre sur Twitter (@Woodgate) si vous souhaitez en discuter.


comments powered by Disqus