Comme de nombreux développeurs j’ai un talon d’Achille : la documentation. Je déteste rédiger une documentation, je ne sais d’ailleurs jamais par quel bout la prendre et je n’en suis jamais satisfaite. Cependant, force m’est de constater que, sans documentation sur laquelle s’appuyer si besoin, il s’avère difficile de savoir ce que l’on a sous les yeux. Voici les points qui me semblent importants pour disposer d’une bonne documentation.

Une documentation ? Pour qui ? Pour quoi ?

La première question que l’on peut se poser, lorsque l’on découvre ou lorsque l’on débute la programmation, c’est pour quoi est-ce que l’on a besoin d’une documentation ? Après tout, si l’on sait programmer et que l’on a accès au code source, c’est suffisant, non ?

Éh bien non ! Ce n’est pas toujours suffisant, malheureusement. Et même si cela peut être réalisé, vous risquez de perdre énormément de temps à comprendre le code source, temps que vous auriez pu consacrer pour réaliser votre script ou votre programme, doc’ incluse. En plus de cela, que ferez-vous si vous souhaitez utiliser une API donc le code est fermé ? Rien. Que pouic. Nada ! Alors certes, vous pourriez vous dire que vous allez chercher sur des fora ou une autre API dont le code source est ouvert, mais la réalité professionnelle n’est pas si simple. Vous n’aurez pas toujours le choix et à ce moment-là vous serez bien incapables d’en faire quoi que ce soit si vous n’avez pas une documentation associée à côté.

Maintenant, prenons l’autre côté auquel on ne songe, parfois, qu’à la fin de son projet : l’utilisateur final. Si vous avez réalisé un programme complet et complexe, et que vous souhaitez qu’il soit utilisé par le plus grand nombre parce que, disons le tout de suite, votre logiciel il déchire, vous serez bien obligés de vous rendre compte qu’il faut rédiger une documentation associée ! Mais voilà, qu’est-ce que Monsieur et Madame Tartampion vont pouvoir faire avec votre bout de code ? Vous devez alors vous mettre à la place de vos utilisateurs.

Je vais tâcher, dans les points suivants, de vous donner des pistes pour rédiger une bonne documentation pour les développeurs, d’un côté, et pour les utilisateurs, d’un autre. Je ne prétends bien sûr pas avoir la recette miracle, tout est une question d’expérience, de ressenti mais également de formation.

La documentation pour le développeur

Si vous avez développé un outil, que j’appelle clés en main, c’est-à-dire un outil qui va permettre à un développeur d’accélérer son temps de programmation en réutilisant des procédures déjà connues et reconnues dans votre domaine, il est important de lui indiquer comment fonctionne votre programme.

En plus de connaître la raison d’être de l’outil et ce qu’il propose, le développeur doit pouvoir savoir rapidement quels sont :

• les paramètres ;
• les variables ;
• les fonctions ;
• les objets.

Documenter les paramètres

Dans le cadre de mon travail, il n’est pas rare que j’ai besoin, pour obtenir nos résultats finaux, d’utiliser plusieurs logiciels ou programmes dans un enchaînement logique, que l’on appelle, communément, pipeline. Dans ce cas, pour chacun des programmes utilisés, je dois pouvoir savoir quels sont les paramètres qui sont demandés comme, par exemple :

• le fichier d’entrée ;
• le fichier de sortie, si nécessaire ;
• l’algorithme de calcul ;
• et d’autres types de paramètres.

Pour le fichier d’entrée, je dois pouvoir savoir quel est le format attendu par le programme. Est-ce que le fichier doit être au format CSV (chaque champ est séparé par une virgule), combien de champs, est-ce qu’il faut des noms spécifiques pour chaque champ ? Si la documentation ne le précise pas alors que le programme s’attend à un format spécifique, je n’aurai, au choix, soit aucun résultat, soit une magnifique erreur. Au mieux l’erreur m’indiquera ce qu’il manque dans le paramètre d’entrée, au pire juste une erreur. Si la documentation ne me le précise pas d’entrée de jeu, je vais passer un temps interminable à savoir ce qui est attendu, m’obligeant parfois à faire des tentatives jusqu’à ce que le programme l’accepte.

Si le programme a nécessairement besoin d’écrire un fichier de sortie, je dois également le savoir, sinon je m’attendrai à ce que le résultat sorte sur la sortie standard (sur le terminal). Or, si l’outil ne me le précise pas, j’aurai, au mieux, une erreur, au pire, rien du tout. Si je n’ai aucune erreur et que rien n’apparaît, ni dans mes répertoires, ni sur mon terminal, je vais penser que le programme ne fonctionne pas et je vais donc, vraisemblablement, le passer à la trappe.

Si il faut également préciser un algorithme pour le ou les différents calculs, il faut également que je sache quels algorithmes sont utilisés, sinon il y a de grandes chances, pour le meilleur des cas, que ce soit l’algorithme par défaut qui soit utilisé. À condition que je sache quel est l’algorithme utilisé, ce qui peut souvent s’avérer vital pour la suite des différents calculs que je vais réaliser.

Bref, vous l’aurez compris, un outil clés en main, c’est bien, mais s’il exige des paramètres spécifiques, le développeur, et même l’utilisateur, doit les connaître. En Sciences, c’est même vital pour être sûrs de nos résultats !

Documenter les variables

Si l’on utilise une bibliothèque pour faire notre propre programme, il est important de savoir quelles sont les variables définies par la bibliothèque. Pourquoi ? Tout simplement pour éviter d’utiliser une variable déjà utilisée qui pourrait entraîner un mauvais comportement de son propre code. De même qu’en Python il ne me viendrait pas à l’esprit de définir une variable print(), qui est une fonction de base du langage, il ne devrait pas me venir à l’esprit d’utiliser un nom de variable utilisée et utilisable par une bibliothèque externe.

Je dois également savoir quel est le type de la variable utilisée par la bibliothèque. Autant en Python, le typage est dynamique, c’est à dire que le langage se débrouille pour “deviner” le type de la variable, autant en Java, qui est un peu plus bas niveau, il est vital de connaître le type. Si la variable est un entier et que je définis une chaîne de caractères, je dois savoir que je dois d’abord la caster, c’est-à-dire la transformer dans le type voulu.

Documenter les fonctions

Ah les fonctions. Dès que l’on apprend à programmer et qu’on les découvre, c’est un merveilleux monde de partitionnement (ou découpage en bouts plus petits) de code qui s’offre à nous ! On aurait parfois tendance à les préférer aux boucles qui nous économisent, elles aussi, de nombreux copiés-collés qui seront difficiles à maintenir. Ici aussi, si l’on utilise un nom de fonction qui est également un nom de fonction de la bibliothèque externe importée, on peut vite se retrouver avec un comportement inattendu, voire à un refus de la part du compilateur. Il est donc, là aussi, important de savoir quelles sont les fonctions existantes dans les bibliothèques utilisées. Il ne vous viendrait tout de même pas à l’esprit de définir une fonction de lecture d’un fichier, alors que votre langage l’implémente déjà et s’en sort très bien tout seul ?

Je dois également savoir quelle est la liste des paramètres attendus par la fonction. Certaines fonctions se contentent de retourner un résultat, et ne nécessitent donc pas d’arguments, mais d’autres ont besoin d’un ou plusieurs paramètres pour les différentes opérations effectuées. Là aussi, si je ne le sais pas, je vais avoir beaucoup de mal à utiliser la bibliothèque !

Documenter les objets

Pour les objets, certains peuvent se demander où je veux en venir. Et bien tout simplement sur le fait que, en programmation objet, il peut être tentant d’utiliser le polymorphisme sur un objet existant. Mais si l’on ne sait pas quelles sont les méthodes implémentées, ne court-on pas un risque de surcharger inutilement notre objet ? De même, si l’on souhaite ajouter une méthode, ne serait-il pas plus judicieux de savoir si ce que l’on va implémenter n’est pas déjà prévu ? Il en va de même pour les classes héritées. Si l’on peut s’économiser le temps nécessaire pour implémenter la classe Chat() héritée de la classe Animal(), c’est parfait !

La documentation pour l’utilisateur final

La première question que l’on doit se poser, c’est quel est l’utilisateur final. La seconde à se poser est, comment doit être formulée cette documentation.

Si l’utilisateur final est un développeur, une documentation telle que je l’ai développé dans le point précédent peut suffire, mais si l’utilisateur n’a aucune notion de programmation ou très peu, elle doit être suffisamment claire pour qu’il puisse utiliser le programme.

De manière générale, un utilisateur doit savoir quel est le but du programme, quel est le sujet pour lequel il a été réalisé et comment il s’utilise. Est-ce qu’il s’agit d’un programme en ligne de commande ? Est-ce qu’il s’agit d’un programme reposant sur une interface web ? Est-ce qu’il s’agit d’un logiciel ?

Dans le cadre de la ligne de commande, un utilisateur lambda, par exemple, un biologiste, doit savoir comment appeler le programme et comment les arguments doivent être utilisés, mais également dans quel ordre, si nécessaire. Il doit également savoir si le fichier qu’il va fournir en entrée est dans le format attendu ou s’il doit en préparer un plus adéquat. Il faut aussi qu’il sache comment le résultat est affiché, est-ce qu’il apparaîtra au même endroit que là où est appelé le programme ou est-ce qu’il va écrire dans un fichier ? De même, quel sera le format de sortie ? Est-ce un format spécifique que connaît l’utilisateur ou un plus exotique qu’il faudra également documenter ?

S’il s’agit d’une application web, comment l’utilisateur doit-il faire pour l’installer puis l’utiliser ? Est-ce que l’interface contient de nombreux menus ou juste un simple formulaire ? S’il s’agit d’un simple formulaire, comment doit-il renseigner les champs ? Et comment le résultat sera-t-il affiché ? Est-ce que le programme va tourner longtemps ou est-ce que le résultat sera instantané ?

Pour un logiciel, les mêmes questions que pour l’interface web se poseront quoi qu’il en soit à l’utilisateur. Par chance, vous pourrez également y intégrer une documentation, pensez-y autant que possible, ça peut faciliter la vie !

Dans tous les cas, vous devez vous demander si la documentation est assez claire pour que n’importe qui puisse utiliser votre programme sans se retrouver bêtement bloqué. Si vous souhaitez qu’il soit utilisé par le plus grand nombre, demandez-vous si votre petit frère ou votre petite sœur, qui n’y connaissent rien du tout en informatique, seront à même de l’utiliser correctement, juste en s’aidant de la documentation et de quelques exemples bien sentis.

La documentation pour la pérennité du projet

En dehors d’une documentation pour un programme, il peut également être primordial d’avoir une documentation claire, précise et exhaustive de votre projet. Pourquoi ? Tout simplement parce que vous pouvez être amenés à collaborer avec d’autres personnes. Aurez-vous toujours suffisamment de temps à leur consacrer pour les former ? Sauront-ils facilement quelles sont les données utilisées, comment elles ont été générées et dans quel but ?

Il n’y a rien de plus déroutant que de débarquer sur un projet qui a déjà X années d’existence et de devoir se mettre rapidement à niveau tout en étant dans le flou le plus total. Si vous avez une documentation et qu’il faut en moyenne un mois à une personne extérieure pour s’approprier toutes les informations, il vaut mieux que la personne ait toutes les clés en main pour comprendre que de se rendre compte, au bout de dix mois, que la personne n’a encore qu’une vague idée de ce sur quoi elle travaille.

De plus, si votre projet à une date de fin et que vous devez rendre un compte-rendu de tout ce que vous avez fait dans les dix dernières années, rien que pour vous faciliter la tâche, vous serez vous même reconnaissant d’avoir une documentation complète pour ne pas piétiner ni perdre de temps à vous demander pourquoi vous avez codé cette fonction de cette façon plutôt que d’une autre.

Facilitez donc la vie des développeurs, des utilisateurs, de vos collaborateurs et de vous même : faites-vous violence et pensez, dès que possible, à rédiger une documentation la plus complète et juste que possible !

---

Source de l’image d’accroche : Documentation, par geralt, sous licence CC0 sur Pixabay