De l'usage du wiki pour la documentation interne

Pendant longtemps a Cocoon Technologies, nous avons utilisé comme documentation de développement un répertoire de documents HTML, le tout dans un repository CVS et nous en étions globalement satisfaits.
Cependant cette documentation souffrait de plusieurs défauts:

• obsolescence: comme dans beaucoup d'environnements de développement, les personnes qui écrivent le code se soucient assez peu de le documenter, ceci étant une tache ingrate et peu valorisante. Dans le monde du logiciel libre et non libre c'est un problème récurrent, mais pas inévitable. Par exemple les systèmes BSD sont excellemment documentés de même que le projet Gentoo Linux.
  
• difficulté d'accès: il faut donc avoir un accès au moins en lecture au repository CVS de notre application, et donc les technico-commerciaux n'ont jamais un accès instantané a la dernière version de la documentation
• difficulté de mise a jour: les développeurs écrivent directement le code HTML, sans utiliser d'éditeur WYSIWYG, ce qui demande un effort supplémentaire pour passer a l'écriture directe de la documentation.

Voici a quoi ressemblait une page de l'ancienne documentation:



Finalement nous sommes passes a un wiki, plus exactement a DokuWiki que je connaissais en bien pour l'avoir vu en action chez gcu squad. Cela permet de résoudre au moins les points 2, et 3 , et en résolvant le point difficulté de mises a jour, j'espère que le point obsolescence va s'améliorer.
Le grep dans les fichiers de documentation est donc maintenant remplace par la boite de recherche intégrée, et la gestion des révisions avec cvs -r se fait maintenant avec une interface web. L'aspect esthetique est bien sur a ne pas négliger avec des pages valides XHTML 1.0.

La même page dans Dokuwiki:



Le seul inconvénient que je vois a l'utilisation d'un wiki interne est la nécessite d'apprendre Yet Another Markup Language, mais peut être cela incitera plus les gens a contribuer a Wikipedia, dont la syntaxe wiki est très proche.