Quel moteur pour un site de documentation

Cette semaine, j’ai cherché le logiciel idéal pour faire un site de documentation du SI.

Nous sommes en 2014 et ça faisait très longtemps que je ne m’étais pas fait un état de l’art.

J’ai passé en revue pas mal de logiciels avec une forte préférence pour ceux qui utilisent des fichiers plats. C’est beaucoup plus facile à manipuler et à sauvegarder que les bases de données. Aucun intérêt d’utiliser une base de données pour des petits logiciels.

En plus les fichiers plats permettent de faire facilement de la synchronisation via, rsync ou git.

Git, fichiers plats, sites statiques :

J’avais déjà parlé de Gitit, un logiciel qui prend un répertoire Git rempli de fichiers écrits en markdown et qui le transforme en Wiki du type mediawiki. Les commits de git représentent les versions des pages. Le principe est super mais c’est écrit en Haskell alors si un jour il faut débugger, ça risque d’être compliqué ! Pour ceux que ça intéresse, j’avais fait un Dockerfile.
Gollum fait un peu la même chose mais avec du Ruby. Après quelques galères de gem install j’ai laissé tombé.
Un tour sur Github m’a orienté vers Mkdocs, un générateur de site statique à partir de fichiers Markdown. Il peut lui aussi se synchroniser avec un Git. Il a l’immense avantage d’être écrit en Python mais comme inconvénient d’être purement statique et donc de ne pas pouvoir modifier les pages par l’interface Web (contrairement à gitit, par exemple).
Wikitten est un peu dans le même genre mais écrit en PHP. En plus du markdown, il reconnaît et colore les pages écrites dans les langages les plus communs. Comme avec mkdocs, on ne peut rien modifier par l’interface Web.

CMS et consort :

Rien de satisfaisant du côté des moteurs de sites/wiki en fichiers plats. Je me tourne alors vers les CMS :

Tout sauf WordPress , que j’utilise à titre perso mais que je ne recommande pas spécialement. Bourré de failles, forcément lié à une base de données, compliqué à migrer vers une autre plateforme. Et ce que je dis sur WordPress est encore pire sur Joomla.
Drupal, j’ai un bon a priori dessus (peut-être pas justifié). Il a l’air un peu moins lourd que les deux autres mais je suis toujours lié à une base de données. En test, la VM avec SQLite était très (très) lente alors que je veux juste afficher/rédiger du texte !!!
Je me serais presque rabattu sur Ghost, un moteur de blog très à la mode, léger, mais bon il n’est pas adapté pour de la documentation et je n’ai pas envie de mettre les mains dans Node.js.

Les bon vieux Wiki :

Y a plus qu’à retourner voir les bons vieux Wikis des années 2000. Ca au moins, c’est fait dans le but de documenter.

Moinmoin est tout à fait correct (à part l’interface un peu brute). Ecrit en Python, il fait du Wiki basé sur des fichiers plats. Les articles peuvent se rédiger en interface Web avec la syntaxe Wiki. On peut y ajouter un plugin pour rédiger en Markdown (je préfère).
Finalement ça m’a paru comme une évidence mais je suis retombé dessus en dernier : Dokuwiki (en PHP) qui utilise directement des fichiers texte dans un répertoire. C’est très facile à sauvegarder/restaurer/migrer en cas de besoin. Ça se rédige en syntaxe Wiki de préférence.

Pour conclure, l’état de l’art des moteurs de documentation Web n’est pas tellement différent de ce qu’il était il y a quelques années. Ces derniers temps, il y a un fort développement des moteurs de sites statiques (Pelican, MKdocs, …). J’aime bien le principe mais l’avantage de Dokuwiki c’est que la structure du site est déjà là et que c’est éditable par des utilisateurs qui n’ont ni VI ni Emacs (non, tout le monde ne l’a pas) !