Dans cette article, j'aimerais m'attarder sur un aspect de la documentation auquel, honte sur moi, je n'ai commencé à m'intéresser que très (trop) récemment : la documentation métier d'une l'application.
Pour comprendre ce que je veux dire par « documentation métier », il faut commencer par reconnaitre que le terme « documentation » recouvre plusieurs choses bien différentes, que ce soit le public qu'elles visent ou la manière dont elles sont écrites.
Pour simplifier un peu, il est possible d'écrire de la documentation pour :
- les développ·euse·eur·s, pour qu'ielles comprennent pourquoi et comment le logiciel fonctionne en interne ;
- les personnes du métier, pour qu'ielles comprennent les tâches que l'application peut réaliser ; et
- les utilisat·rice·eur·s, pour qu'ielles sachent comment réaliser ces tâches.
Pour un public de développ·euse·eur·s, la documentation est souvent écrite sous forme
de commentaire (ou de docstring en Python) directement dans le code. L'information
de « pourquoi » un bout de code a été écrit comme il l'a été est donc au plus proche du code,
là où nous en avons besoin. Cette documentation est en général assez stable et évolue
en même temps que le code qu'elle concerne.
Pour les utilisat·rice·eur·s « finaux » (les personnes qui cliquent dans un navigateur dans le cas d'une application web), la documentation peut être sous forme d'une procédure écrite (souvent accompagnée de copie d'écran) ou de tutoriels vidéo. Le but de cette documentation est d'expliquer comment réaliser une tâche particulière en utilisant l'interface à disposition. Cette documentation est en général assez difficile à produire (surtout les vidéo) et est souvent la première à ne plus être à jour. Je dois avouer que c'est celle que j'aime le moins écrire, et je la délègue souvent entièrement aux client·e·s.
Pour les personnes du métier, la documentation est souvent… inexistante !? En effet, les personnes du métier étant supposées connaitre le métier, il parait souvent inutile de mettre par écrit ce qui est (apparemment) évident. Mais, avec un peu de recule, je pense que c'est une erreur.
La raison la plus évidente est le facteur bus. Les gens ne sont en effet par éternels et le savoir à une facheuse tendance à quitter les équipes. Mais, pour les personnes comme moi, c'est souvent l'effet Dory qui prime : j'ai tendance à un peu oublier les choses ! Le fait de travailler sur plusieurs projets dans des domaines métiers complètement différents ne doit pas aider non plus. Le meilleur moyen de ne pas perdre ce savoir est encore de le mettre par écrit.
Ma bonne résolution 2023 sera donc de documenter les tâches métier sur mes nouveaux projets et, dans la mesure du possible, de le faire aussi sur mes projets en cours !
… bon, j'avoue, j'ai un peu triché, et j'ai déjà commencé l'année passée à explorer différentes manières de faire. Et j'ai fini par un trouver une qui me satisfait.
L'idée est d'écrire un texte documentant la partie métier et de la publier sous forme d'un site web. La documentation pourra ainsi être consulter facilement par tou·te·s. Mais attention, le secret est de ne documenter que le strict minimum pour ne pas se retrouver avec des duplications difficiles à maintenir. Le but est donc de documenter les « pièces » existantes et comment elles s'articulent entre elles.
Une version minimaliste¶
La documentation devant être minimale, elle dont donc contenir des liens vers les informations additionnelles présentes à d'autres endroits, que ce soit dans le code ou ailleurs.
Pour le projet Listsém de l'EHESS, j'ai assumé le fait de renvoyer directement vers les fichiers Python concernés. Par exemple, pour documenter le cycle de vie des séminaires, j'ai mis des liens vers le code Python de mes cas d'usage (i.e. un scénario d'utilisation).
Vous pouvez consulter le résultat sur la documentation en ligne.
Une version plus aboutie¶
Plutôt que de faire des liens vers le code —ce qui est un peu hardcore pour les personnes « normales » !—,
il est possible de faire un lien vers les tests ou vers les spécifications, car celles-ci
sont supposées être plus lisibles et décrire le comportement du composant concerné.
Il est même possible de les inclure directement dans la documentation et de les mettre dans
des codeblock. Mais lire des tests, cela revient à lire du code Python, non ?!
Et bien, pas forcement ! C'est en effet là que Behave
rentre en jeu !
Behave est un cadre logiciel de test qui permet d'écrire des spécifications en collaboration avec les personnes du métier. Une syntaxe très simple permet d'écrire des scénarios d'utilisation (a.k.a. des cas d'usage) dans des fichiers de features (en Français ou en n'importe quelle autre langue prise en charge), et de s'en servir pour exécuter du code de test de l'application. Malheureusement, tout ceci n'est pas magique et, pour faire le lien entre les fichiers feature et le code Python, il faut écrire du glue code appelé steps. Mais, avec un peu d'expérience et de rigueur, cela est très facilement réalisable.
Voici un exemple de fichier de feature du projet SENéo :
Fonctionnalité: saisir un service complémentaire
Afin de remplir mes obligations de services
En tant qu'enseignant·e
Je dois pouvoir saisir un service complémentaire
Contexte:
Soit une base de services vide
Et je suis connecté·e comme enseignant·e
Scénario: saisie correcte
Quand je saisis un service
Alors un nouveau service a été enregistré
Scénario: activité inconnue
Quand je saisis un service pour l'activité "INCONNUE"
Alors je dois être notifié·e du problème de code
Scénario: durée manquante
Quand je saisis un service avec une durée de 0 heure(s)
Alors je dois être notifié·e du problème de durée (manquante)
Scénario: durée incorrecte
Quand je saisis un service avec une durée de -1 heure(s)
Alors je dois être notifié·e du problème de durée (incorrecte)
Le glue code, pour sa part, ressemble à cela :
@then("un nouveau service a été enregistré") # type: ignore
def step_impl(context):
expect(context.presenter.service_enregistre).to.have.been.called()
Une fois inclus et publié dans la documentation en ligne cela donne quelque chose de beaucoup plus lisible que du code.
Au passage, vous pouvez voir comment, dans le cas du projet SENéo, la présentation de l'application se concentre uniquement sur la liste des tâches réalisables par l'application et leurs relations entre elles.
Conclusion¶
Je dois avouer que je suis assez satisfait du résultat final, du moins de la version avec les features de Behave. Elle permet d'avoir une bonne idée de ce que l'application est capable de faire et de décrire la manière dont sont orchestrés les processus métier.
Malheureusement, tous les projets ne sont pas assez complexes ou « riches », au sens métier du terme, pour nécessiter l'écriture de cas d'usage. Mais, même dans ce cas là, je trouve qu'une documentation métier renvoyant vers du code Python… n'est pas totalement déconnante. Elle a le mérite de pouvoir écrire une belle présentation de l'application.
J'espère que ce article vous aura donné envie de consacrer plus de temps à l'écriture de la documentation métier de vos applications. Pour ma part, je vais peut-être consacrer un peu de temps en 2023 à… la documentation finale utilisateur !
behind the scenes : Les détails d'implémentation¶
Concrètement, la documentation métier est écrite en Markdown dans un dossier dédié. Celui-ci est transformé en collection de pages HTML par Mkdocs, puis publié et servi comme pages dans notre Gitlab. Tout ceci est fait automatiquement grâce à la CI de Gitlab.