1 octobre 2020 Nicolas Delauney

Une documentation pour tous

La documentation, dans le monde de la tech, tout le monde en parle. On en voudrait partout, mais personne (ou presque) ne veut l’écrire. Alors, fantasme ou perte de temps ? Décryptons ensemble tout ce qui se cache derrière le mot « documentation ».

Kézako ?

La documentation d’un produit regroupe l’ensemble des documents (textes, schémas, vidéos, commentaires, …) nécessaires à la compréhension et/ou l’utilisation de celui-ci. Autant dire que « la documentation » n’a pas vraiment de sens, car il existe en réalité « des documentations » pour un même produit, chacune ayant pour cible un public différent : utilisateur final, managers, développeurs d’une autre équipe, développeurs d’une même équipe… Et chacune est potentiellement rédigée par une personne différente.

savoir c'est pouvoir

Mais cette somme de documents est souvent négligée, surtout pour les parties les plus techniques, regardée par les équipes comme une perte de temps, ou tout du moins une tâche non prioritaire. Les développeurs en particulier sont les premiers à négliger la documentation du code, et les premiers à pester sur du code non documenté. En effet, une documentation complète et à jour représente très souvent un gain de temps énorme : on connait rapidement le contexte, ce qu’il est possible de faire et comment.

Avez-vous déjà entendu parlé du « facteur d’autobus » (de l’anglais bus factor) ? C’est une mesure du risque qui imagine le cas ou un membre (ou plus) d’un équipe n’est plus en mesure de communiquer ses connaissances, et peut être résumée ainsi : « Combien de personnes clés dans votre équipe peuvent se faire renverser par un autobus avant que votre projet échoue ? ». Maintenir cette documentation, c’est réduire ce facteur, car n’importe quel nouvel arrivant dans une équipe peut monter en compétence sur le sujet en autonomie.

Autobus by unsplash

Et combien de bus pour faire échouer votre projet ?

Voyons ensemble les différents niveaux de documentation, du moins au plus technique.

La documentation utilisateur

La première marche de la documentation, c’est la documentation utilisateur. Lorsqu’on achète un produit, il est souvent accompagné d’un manuel, d’une FAQ, ou d’une série de vidéos explicatives. Le but de cette documentation est simple : n’importe qui, sans aucune connaissance préalable, doit pouvoir utiliser le produit après la lecture. Cela implique une bonne rédaction, des compétences didactiques, et peu de complexité, ou alors une complexité croissante. Trop abstrait ? L’exemple par excellence de la documentation utilisateur est un manuel de construction d’un meuble d’une célèbre chaine suédoise. Quelques images, quelques pictogrammes, et vous voilà menuisier(e) en 10min.

L’investissement initial lors de sa rédaction peut paraître fastidieux, mais c’est autant de temps que l’équipe ne passera pas en service après vente.

La FAQ quand a elle a l’avantage de s’écrire au fil de l’eau. Il est bon de commencer avec quelques questions, mais le principe est de compléter la collection de réponse au fur et à mesure que de nouvelles questions apparaissent

La documentation interne

La documentation interne

La doc interne

Celle-ci concerne l’ensemble de l’équipe en charge de la production du produit. Le but est double : préparer la documentation utilisateur (en détaillant les fonctionnalités par exemple) et aussi assurer l’historique du projet. Pourquoi telle décision a été prise ? Dans quel contexte ? On y retrouvera par exemple les comptes rendus de réunion. Elle permet aussi de décrire l’architecture du projet : déploiement des serveurs, procédures à appliquer, description des flux d’utilisations, etc etc. A partir de ce niveau de documentation, tout ajout permet de réduire le facteur d’autobus

La documentation technique

La documentation technique se divise en plusieurs de catégories.

Dans l’informatique de gestion on retrouve souvent de la documentation permettant par exemple de décrire le contrat que s’engage à remplir un serveur web. En java le framework le plus utilisé est swagger. Il permet de décrire chaque ressource http exposée: quels paramètres sont attendus en entrée, le format du retour (en json en général), ainsi que les codes http d’erreur.  Cette documentation est en partie autogénérée à partir du code, et en partie écrite manuellement par le développeur.

Swagger-ui

Swagger-ui

Cette documentation est souvent publique et accessible aux développeurs qui vont utiliser ce projet, quels qu’ils soient. Pour pouvoir utiliser un framework, ou une api, il faut savoir ce qu’il est possible de faire et comment via des exemples. Cette documentation de framework se rapproche presque d’une documentation utilisateur, sauf que l’utilisateur est considéré comme avancé et apte à comprendre par lui même certaines choses.

vuejs

Capture d’écran de la doc du framework Vue.js

Parmi la documentation technique il faut également ajouter les tests unitaires et d’intégration. En effet, ceux-ci permettent de documenter le comportement attendu d’objets ou de services, ainsi que le comportement du système dans sa globalité. Cette documentation a pour avantage d’être nécessairement à jour par rapport au code. En revanche, il faut pouvoir accéder au code source, et l’exécuter, pour en bénéficier. Cette documentation est donc moins accessible que de la documentation textuelle, et fait partie de la documentation « interne ». Elle peut représenter toutefois un gage de qualité publique : annoncer une bonne couverture du code permet de donner confiance sur le comportement attendu.

La documentation du code

Parmi la documentation textuelle la plus connue dans le monde java on peut trouver la javadoc. Inventée par Oracle, elle permet de décrire en html le comportement attendu d’une méthode ou d’une classe, ou le sens d’un variable. Le JDK permet de compiler toutes ces annotations dans un même document html, centralisant de ce fait la documentation de l’application au même endroit.

Un exemple de Javadoc

Un exemple de Javadoc

Si cette documentation est très largement utilisée, elle a pour défaut de ne pas forcément évoluer avec le code: il appartient au développeur de s’assurer qu’il modifie bien la documentation en même temps que le code. Elle peut également manquer de pertinence: elle peut être redondante avec le code, ou décrire du code qui n’est pas public, et donc pas destiné à être utilisé en dehors du système. Une bonne documentation décrira le comportement du code, avec potentiellement des exemples d’appel de méthode. En cela, on peut considérer que son rôle est redondant avec les tests unitaires lorsque ceux-ci sont disponibles.

Chaque langage a ensuite emboité le pas au Java et a implémenté une forme de documentation. Dans les outils de développements modernes (IDE), cette documentation est récupérée pour être affichée contextuellement. Ainsi, lorsqu’on appelle une méthode, on sait quels paramètres utiliser, et quel retour attendre, sans avoir besoin de lire du code (qui parfois n’est pas accessible). Lorsque vous utilisez la fonction du précédent exemple, voici ce qu’un IDE vous affichera :

documentation contextualisée

La doc contextualisée

La documentation dont vous avez besoin, là ou vous en avez besoin. Que demander de plus ?

Le code auto-documenté

Le code source lui-même peut-être considéré comme étant sa propre documentation. Ainsi, une méthode ou une variable bien nommée suffisent souvent à ce que l’on puisse comprendre le sens du code sous-jacent, nous en parlions dans un précédent article.

Attention au nommage

Attention au nommage !

Jugez plutôt:

Il est ici évident ici que l’on modifie l’adresse d’une personne, sans doute parce que celle-ci a déménagé. Du code suffisamment explicite n’a pas besoin de documentation externe pour être compris, si on se donne la peine de le lire. En règle générale on essaiera d’utiliser des mots précis, compréhensibles sans ambiguïté par le lecteur. On évitera ainsi pour les classes des noms trop génériques, comme Manager, ou Service. On privilégiera pour les méthodes un verbe suivi d’un nom, comme modifierAdresse, supprimerUtilisateur, ou revoquerDroits.

Cette sorte de documentation s’adresse uniquement aux développeurs qui travaillent activement sur un projet informatique. En effet, on aura tendance à privilégier la javadoc lorsque l’on veut savoir comment se comporte un programme, et on pestera si l’on doit lire le code source pour en comprendre le comportement.

Au final, la documentation s’adresse à tous, et il revient donc à chacun de prendre la responsabilité de la maintenir. Cette tâche fastidieuse peut être découpée, et rédigée au fur et à mesure de la vie du projet, et tout le monde vous remerciera de cette implication. Une bonne documentation est un gage de qualité et de maintenabilité. À vos stylos !