Ne lisez pas ce site… forkez-le sur GitHub !

Ce site présente comment gérer la documentation technique comme le code source, à partir de fichiers sources en format texte. Toutes les versions de ce site sont gérées sous le logiciel de gestion de versions décentralisé Git. Il est disponible en trois formats, basés sur la version 1.1 [1]. Ces formats présentent des niveaux de fonctionnalités et de complexité différents.

Niveau de fonctionnalités et de complexité des formats texte

reStructuredText

Langage de balisage léger de type Wiki ou Markdown qui, combiné au générateur de documentation Sphinx, offre un bon niveau de fonctionnalités.

DITA XML

Architecture documentaire XML sémantique et modulaire complexe qui offre des gains de productivité importants grâce à une forte réutilisation du contenu.

DocBook

Langage de balisage XML sémantique qui offre un rapport fonctionnalités/complexité aujourd’hui peu intéressant.

Ce site est conçu et réalisé par un rédacteur technique spécialisé dans l’informatique. Il est publié sous licence Creative Commons. Vous pouvez le cloner, le forker, proposer des patchs, ou… le lire, dans le format que vous souhaitez, après l’avoir compilé en PDF, EPUB ou autre avec Python Sphinx.

Puisqu’il traite des processus et des formats de rédaction technique, son contenu est cependant moins pertinent que son historique et que ses branches Git. Pour tirer le meilleur parti des formats texte, il faut en effet gérer ses sources sous un logiciel de gestion de versions tel que Git ou Subversion. Les modifications de contenu peuvent alors être :

• regroupées par lots cohérents,
• liées à un ticket de logiciel de suivi de problèmes tel que Bugzilla ou Trac,
• validées par des pairs,
• partagées entre différentes versions du projet de documentation,
• annulées en une seule opération, etc.

Ce site a parlé, parle ou parlera également un peu, beaucoup ou pas du tout de :

		reStructuredText	DITA XML
Modification		scripts Bash
		awk
		sed
		expressions rationnelles (ou expressions régulières)
Gestion de versions		Git
Compilation		Makefile	Ant
			XSLT
Mise en page	HTML	CSS
	PDF	LaTeX	XSL-FO

Notes

[1]	Seule la version reStructuredText, à partir de laquelle cette version HTML est créée, est maintenue.