Dans le cadre d'un de nos projets chez Viveris, un client nous a demandé de mettre en place un wiki partagé pour pouvoir échanger des informations avec nous. Ils utilisent habituellement le logiciel propriétaire Confluence. Cependant, Atlassian, l'éditeur de ce logiciel, a modifié son offre commerciale et il n'est plus possible d'acheter des licences pour la version auto hébergée. Dans notre cas nous ne souhaitons pas héberger notre documentation sur des serveurs contrôlés par Atlassian.
Nous avons donc cherché d'autres solutions et notre choix s'est porté sur XWiki (LGPL 2 1). Cela fait maintenant 2 ans qu'on l'utilise, on vous explique ici ce qu'on fait avec et on fait un retour d'expérience.
Le wiki fonctionne bien et nous l'avons rempli avec plein d'informations utiles sur notre projet. Cependant nous avons rencontré quelques problèmes avec l'installation par défaut.
Il n'est pas possible d'ordonner les pages comme on veut dans la table des matières. Elles sont toujours triées par ordre alphabétique, ce qui ne convient pas forcément. Dans un premier temps nous avons contourné le problème en numérotant manuellement nos pages, mais cela pose problème dès qu'on veut insérer une nouvelle page entre deux autres.
Un autre souci est que l'export du wiki en HTML ou PDF n'est pas suffisant pour nos besoins. La version HTML ne contient pas, par exemple, les tables des matières qui sont présentes sur les pages du wiki "live". L'export PDF génère un fichier pour chaque page, ce qui n'est pas pratique pour naviguer dedans.
Dans notre cas, XWiki est maintenant utilisé pour rédiger toute la documentation utilisateur de notre logiciel, et il est important de pouvoir exporter une version figée de cette documentation avec chaque livraison du logiciel (toutes les 3 semaines, puisqu'on travaille en méthodes agiles).
Nous avons donc recruté un stagiaire pour développer une solution d'export convenant mieux à nos besoins.
Dans un premier temps nous avons essayé d'utiliser le plugin multipage-pdf-export, cependant, ce dernier n'est plus maintenu et ne fonctionne pas du tout avec les versions actuelles de XWiki. Après discussion avec les développeurs de XWiki, nous avons donc déployé l'application application-documentation qui est conçue pour cet usage. Elle est développée par l'entreprise XWiki SAS et utilisée par plusieurs de leurs clients. Le code source est disponible, mais peu documenté.
Les développeurs XWiki nous ont également fourni un script (développé dans le langage Velocity qui permet d'accéder aux APIs de XWiki) permettant de générer un export PDF contenant toutes les pages de la documentation. Ce script nous a servi de base mais nous avons du le modifier pour ajouter différentes choses:
- Gestion des pièces jointes dans les pages pour récupérer nos illustrations, schémas et captures d'écrans
- Modification des niveaux de titres dans les pages pour avoir une numérotation cohérente
- Personnalisation de la page de page de garde, des en-têtes et des pieds de pages pour générer un document conforme aux règles du projet
Un problème qui s'est posé est la migration des pages existantes vers l'application-documentation. En effet il ne semble pas y avoir dans XWiki de moyen de déplacer une page d'une application vers une autre. Il semble que cela poserait des problèmes dans la base de données car chaque application peut ajouter diverses données aux pages qu'elle contient, et si on déplace les pages sans y prendre garde, ces données pourraient être manquantes.
Nous avons commencé le développement d'une fonction pour importer des pages dans l'application, cependant, par manque de temps, nous n'avons pas pu la terminer. Comme pour l'instant nous utilisons XWiki sur un seul projet, nous avons décidé de recréer nos pages dans l'application et de déplacer manuellement le contenu. Pas très fun, mais il n'y a finalement qu'une centaine de pages. Pour les prochains projets il suffira de configurer le wiki dès le départ avec la bonne application pour architecturer la documentation.
Finalement, nous sommes satisfaits de l'utilisation de XWiki et de l'aide apportée par les développeurs pour l'utiliser correctement. Il est dommage que la solution mise en place dans notre cas repose sur des composants qui ne font pas partie de l'installation de base ou des greffons proposés publiquement pour XWiki. Cependant, on a quand même pu s'en sortir.
Dans le dépôt git vous pourrez trouver la documentation pour installer l'application et le script sur un XWiki. Cette documentation au format PDF est générée en utilisant l'outil développé et vous donnera une idée du résultat obtenu.
Nous allons recommander cette solution à nos collègues pour d'autres projets et peut-être aussi à nos clients qui auraient la même problématique.
