Clochix

Lorsqu'on a rédiger une documentation, qu'elle soit technique ou destination des utilisateurs et des utilisatrices finales, le premier réflexe est souvent de lancer un traitement de texte généraliste, parce que c'est un logiciel installé par défaut sur la majorité des postes bureautiques et dont l'utilisation de base est relativement maîtrisée. Et d'expérience, ce traitement de texte est souvent Microsoft Word. Un peu de réflexion suffit pourtant trouver les limites de cette solution:

• le format des fichiers est fermé, et pose des problèmes en terme de pérennité (pourra-t-on relire le document dans quelques années^[1]) et de compatibilité (le document sera-t-il lisible sans perte d'information sur d'autres systèmes d'information).
• les données sont enregistrées dans un format binaire, ce qui rend difficile l'utilisation d'outils de suivi des révisions externes (on peut certes utiliser les fonctionnalités de Word pour suivre les modifications, mais elles sont assez limitées et l encore, rien ne garantit leur compatibilité avec d'autres logiciels)
• l'export vers d'autres formats (typiquement le HTML) n'est pas très aisé (une page HTML générée par Word est franchement laide AMHA)
• la recherche dans de multiples documents nécessite l'utilisation de moteurs sachant interpréter le format de fichier. L encore rien ne garantit que dans 10 ans les outils de recherche sauront encore lire du Word 2000.
• le fond et la forme du document sont mélangés. D'où des difficultés assurer une cohérence entre tous les documents, des fichiers inutilement gros, une sémantique faible...

Toutes ces raisons et celles que j'oublie mènent rapidement la conclusion de la nécessité d'utiliser un format ouvert, en texte pur, structuré pour permettre l'automatisation de traitements, etc. XML par exemple. La plupart des traitements de texte permettent d'enregistrer des documents dans un format basé sur XML, mais ceux-ci ne remplissent que partiellement les besoins de séparation de la forme et du fond, et de structuration sémantique des documents. Mieux vaut mon avis se tourner vers un format spécialement créé pour gérer des documentations, DocBook.

Il y a longtemps que j'y jette des coups d'oeil, mais étais jusqu' présent rebuté par 2 "problèmes", disons 2 obstacles surmonter avant de lancer une campagne d'évangélisation pour convaincre autour de moi de passer DocBook :

• le vocabulaire est vaste et demande une phase d'apprentissage.
• le manque d'outils "user friendly" pour créer des documents. Ce n'est bien sûr que du XML et n'importe quel éditeur de texte générique ou orienté XML suffit, mais l'adoption du format au sein d'une structure ne sera réellement possible que si l'apprentissage est rapide et les outils simples d'utilisation.

Après avoir un peu cherché, je pense avoir résolu ces 2 soucis:

• j'ai trouvé des tutoriels pour apprendre les rudiments du format en quelques minutes:
  • Ecrire un document XML Docbook
  • Écrire de la documentation en utilisant DocBook
  • Utilisation simplifiée de DocBook
• et des éditeurs pas mal du tout:
  • XMLmind XML Editor (XXE) dont la version "standard" est gratuite (mais hélas pas libre). C'est un éditeur écrit en Java (donc multi-plateforme). Pour en savoir plus allez jeter un oeil la liste des fonctionnalités (toutes ne sont malheureusement pas activées dans la version gratuite, qui ne permet par exemple de travailler que sur des documents DocBook ou XHTML. Les traductions vers d'autres formats sont également limitées) ou lisez ce billet. L'éditeur peut être étendu via de nombreux additifs (la version française en est un) et une documentation en français est disponible.
  • Jaxe, manifestement moins puissant mais l'interface peut-être plus intuitive

Bref, ce n'est pas encore parfait, mais je pense qu'avec un peu d'efforts le passage DocBook pour réaliser toutes les documentations est aujourd'hui relativement aisé. Et les avantages sont si nombreux qu'il serait vraiment dommage de s'en priver.

Quelques liens supplémentaires.

• Pourquoi utiliser XML DocBook ?, argumentaire très complet
• le site du projet DocBook avec de nombreuses documentations et des outils, comme des feuilles de style et des transformations XSL pour convertir les documentations DocBook vers de multiples formats.
• l'autre site du projet DocBook : toutes les documentations, les shémas, etc.
• un wiki
• un manuel plus complet

En guise de conclusion, 2 points supplémentaire me viennent l'esprit:

• ce système permet de réaliser des documentations multilingues, il est très simple d'en extraire automatiquement tous les sections dans une langue.
• connaissez-vous Cocoon, un framework développé par la Fondation Apache permettant la réalisation d'application web basées sur des documents XML et des transformations XSLT (en résumant). Une bonne solution pour créer un serveur de documentation.

Quelques ajouts ce billet :

• on peut créer un document au format DocBook directement partir des commentaires dans un programme Java grâce DocBook Doclet. D'autres logiciels de création de documentation partir des commentaires du code source doivent disposer de fonctionnalités similaires, étant donné que le format contient des éléments spécifiques pour décrire des classes par exemple.