Un collègue m’a fourni une vidéo intéressante sur une manidère différente de gérer une documentation projet : https://youtu.be/1rKgVF5CEEY
Il est vrai que cela fait un moment qu’on tourne autour du pot. Les wikis c’est bien mais le bon logiciel est toujours délicat à trouver. Sans détailler la réflexion ici (peut être une autre fois) il y a toujours une contrainte qui fait que ce n’est jamais parfait…
Je suis donc en train de me pencher sur une mouvance qui me semble intéressante : gérer sa documention as a code. En simplifiant cela veut dire que votre documentation est gérée dans un dépot git, avec un outil de collaboration sympa comme gitlab et des fichiers sous forme plain text avec une syntaxe simple et lisible comme markdown ou asciidoc (j’ai tendance à préférer le second actuellement).
Cela vous permet d’avoir une documentation où chacun peut collaborer simplement (coucou pull request). De plus, il se trouve que github et gitlab intègrent les syntaxes asciidoc et markdown en natif, vous pouvez donc déjà naviguer dans votre documentation directement sur leur site web.
Le fin du fin sera de générer un site statique joli (avec un moteur de recherche) et si possible une version pdf. C’est là que l’excellent gitbook entre en action.
Enfin, pour mettre la cerise sur le gateau, vous pouvez rebuilder votre site documentaire de manière automatisée avec un job gitlab ci bien senti.
Au passage, pour le job gitlab je me suis construit une image docker gitbook qui m’aide bien.
Cette manière de faire semble s’étendre car même chez owasp on a choisi de construire le nouveau developer guide de cette manière sur github.
Que du bon donc pour l’instant ! A creuser à l’usage.
Le Blog de Alban Montaigu