Hydra est un outil de modélisation hydraulique qui capitalise 40 ans d’expérience. Malgré son grand âge (pour un logiciel) hydra est en constant développement, s’attaquant à de nouveaux domaines d’application tel que le diagnostic permanent en assainissement ou l’aide à la décision dans le contrôle de crues en rivière (teaser : on vous parlera de ça en détail dans un autre article).

Héritage de son histoire, la documentation d’hydra est considérable, tout comme sa base de code. Confier entièrement le fardeau de sa maintenance aux seuls développeurs nous semble inapproprié (c’est un développeur qui vous le dit), les utilisateurs et utilisatrices d’hydra sont en effet :

  • Plus nombreux et nombreuses que les développeurs,
  • Plus compétent·e·s en modélisation hydraulique,
  • Et utilisent un jargon différent.

Ce sont celles et ceux qui lisent la documentation d’hydra, et à ce titre, les premiers intéressés par sa qualité.

Ils ont la compétence, ils ont la motivation, alors : crowdsourcing ! Laissons aux utilisateurs le soin de maintenir la documentation.

Comment ?

Lorsque l’interface d’hydra a été intégré à QGIS, la documentation, un ensemble de documents MS Word permettant de créer des fichiers PDF, a été massivement convertie en texte restructuré (RST pour les intimes). Ce format texte permet de suivre plus facilement les évolutions (différences entre deux versions), de générer de la doc en ligne (html) et de la doc « hors ligne » (pdf) via Sphinx et LaTeX. La documentation a alors été intégrée dans un répertoire sous gestion de version (git) dans le même dépôt que le code du plugin QGIS qui est désormais la partie visible d’hydra (teaser : je vous parlerai de la partie immergée de l’iceberg dans un prochain article).

Les développeurs adorent les fichiers texte, ils ont besoin de versionner les fichiers, de tracer les évolutions qui parfois sont des régressions, ils maîtrisent les syntaxes de plusieurs langages de programmation, ils révèrent git. Après des années d’évangélisation, je dois me rendre à l’évidence : je ne peux pas convertir les utilisateurs et utilisatrices à git.

Une alternative c’est Gitlab, une belle interface web pour cacher aux âmes sensibles la complexité de git. Il y a un éditeur intégré et une prévisualisation du rendu html des fichiers RST (pas WYSIWYG, mais pas loin). Par contre il faut s’inscrire sur la plateforme et il faut apprivoiser l’interface. Elle est plutôt « user-friendly », l’interface Gitlab, et elle permet de faire beaucoup, beaucoup de choses, c’est l’ERP du développeur, si j’ose dire. Résultat de cette réflexion : Gitlab n’est pas vraiment appropriée si tout ce qu’on lui demande c’est de modifier de la doc.

Ah, j’en étais déjà à évaluer une solution technique alors que je n’avais pas encore établi de cahier des charges, mais parfois la solution est tellement évidente que le problème c’est la question. Donc on souhaite :

  • Un truc qui permet d’écrire de la doc
  • De manière collaborative (i.e. plusieurs utilisateurs),
  • Dynamique (les modifications sont rapidement disponibles pour tous),
  • Avec un ticket d’entrée par trop cher,
  • Et dont le format support est du fichier texte.

Et comme les utilisateurs et utilisatrices préfèrent voir le résultat final plutôt que du texte, un WYSIWYG serait optimal.

Comme un wiki correspond à la fiche de poste, ce sera un wiki.

Wiki.js intègre un éditeur avec deux volets (édition et prévisualisation), c’est très bien, le format support c’est du markdown, donc le ticket d’entrée est encore moins cher que celui du RST. Il y’a quelques irritants, dont la synchronisation entre les deux volets qui ne se fait que dans la fenêtre de texte, mais c’est open source, donc si on est trop irrité on pourra corriger et contribuer.

On a pour l’instant perdu le mode de consultation de la documentation hors ligne, pour ceux qui veulent travailler sans être connecté. Mais en cette période de crise sanitaire et de télétravail forcé, qui peut encore travailler sans être connecté ? On pourra générer des PDF à partir du markdown, c’est presque trivial, quand ce sera réclamé.

Cet article veut entrer dans la catégorie « non-technique » ou, à la limite, « faiblement-technique », donc je ne vous parlerai pas des difficultés de conversion RST -> markdown qui nous ont amené à créer notre propre script python de conversion (ont eu du mal avec pandoc) pour conserver les liens et les références et profiter de l’occasion pour relocaliser/reformater des choses en masse. Je ne vous parlerai pas non plus du backend PostgreSQL de Wiki.js (j’adore PostgreSQL) ni du travail rébarbatif pour uploader toutes les images parce que l’api pour ça n’est pas encore là dans Wiki.js (le travail est en cours). Tout ça est derrière nous.

Désormais on a un wiki pour la doc, il est là : http://wiki.hydra-software.net

Épilogue

Je ne vous parlerai pas de technique, mais je peux vous parler d’équations, c’est pas anecdotique : les équations il y en a quelques-unes dans la documentation d’un logiciel de modélisation hydraulique. Pour écrire des équations il y’a LaTeX. Il y a d’autres choses, du mathml par exemple, je vous laisse aller vous convaincre par vous-même sur la page Wikipédia du MathML qu’on ne veut pas taper des équations comme ça. Donc il y a LaTeX. J’ai dit que je ne vous parlerai pas de technique, mais je tire mon chapeau au passage aux programmeurs qui ont fait les outils de conversion LaTeX -> html (avant on appelait le moteur original, on créait une image qu’on mettait sur la page web, là c’est de la vraie mise en page native et c’est beau aussi). Wiki.js supporte les équations dans le markdown : $f(x)$ et ça c’est une très bonne nouvelle, ce serait fantastique que Gitlab supporte cette syntaxe au lieu de `$f(x)$`.

Je ne vous parlerai pas de technique, par contre je peux revenir sur l’ordre des choses, que j’avais apparemment prises dans le désordre. En théorie :

    1. Définition du besoin,
    2. Proposition de solutions,
    3. Implémentation,
    4. Test/validation.

En pratique, on a commencé par le (2.), on est revenu au (1.), on est descendu jusqu’au (4.) avec un utilisateur motivé, et on a remarqué que Wiki.js proposait par défaut des commentaires sur les pages. Du coup, ça a reposé la question du besoin (1.), on les a enlevés (3., 4.). Puis on s’est dit que ce serait pas mal que ce ne soit pas n’importe qui qui édite directement la doc (même si c’est historisé). Finalement, pour l’instant, on a remis les commentaires (3.).

Le processus, qu’on est en train de tester en ce moment (4.), c’est que les utilisateurs et utilisatrices commencent par faire leurs remarques en commentant les pages, il n’a pas à créer de compte, juste à mettre son mail pour pouvoir commenter. Si les commentaires sont pertinents on corrige et on gagne en confiance. Dès qu’on a assez confiance, et que ça devient lourd d’intégrer les modifications de quelqu’un de particulièrement motivé, on crée un compte pour que l’édition soit directe.

L’ordre des choses en théorie et l’ordre dans lequel se font les choses en pratique… Si on prend un V et qu’on pousse sur ses extrémités, on obtient un : on descend, on boucle, on remonte, ça évoque plus un cycle (agile), une boucle (de rétroaction), et on en a fait combien ? En attendant le prochain article, je vous laisse compter.

Vincent, de l’équipe hydra.