La documentation logicielle
J’ai décidé d’écrire un article sur la documentation logicielle car j’ai lu une documentation d’une API(Application Programming Interface) de paiement électronique au Bénin et je n’ai pas apprécié le contenu et la structure de cette dernière. Je tiens à préciser ici, que je ne me déclare pas “spécialiste des documentations logicielles” mais j’ai l’habitude comme la plupart des développeurs de lire les documentations des API ou Frameworks des technologies ou projets open-source et de pouvoir apprécier la qualité du contenu.
L’autre raison qui m’a poussée à écrire cet article est que récemment, j’ai travaillé avec d’autres développeurs de mon entourage et j’ai pu voir constaté l’utilité d’une documentation, minimale soit elle dans la conception d’un logiciel.
Dans cet article, je présente comment réussir un processus de création de documentation logicielle pour ses pairs ( développeurs, ou informaticiens) et pour un public profane (clients par exemple).
Qu’est ce que la documentation ? Quel est son rôle ?
La documentation logicielle est un texte écrit qui explique à un informaticien (programmeur, développeur) comment le logiciel a été conçu et à un néophyte (utilisateur quelconque, donc un client par exemple) comment l’utiliser. Il faut ainsi noter que la documentation peut être destinée à des professionnels ou aux utilisateurs finaux du logiciel.
Un utilisateur final se penchera plus sur la documentation d’utilisation du logiciel tandis qu’un professionnel intéressera à la documentation du processus de création et de fonctionnement du logiciel.
Documenter, oui mais que doit-on y mettre ?
Ian Sommerville dans son article intitulé Software documentation définit trois types de documentation.
En premier lieu, la documentation du processus (en anglais Process Documentation) qui représente l’ensemble des documents liés à l’architecture du logiciel à concevoir, les technologies, les standards de programmation, les évolutions, les conventions, en un mot, le processus de développement du logiciel. Dans ce type de documentation, on devrait mettre tout ce qui a rapport aux chronogrammes définit dans notre projet logiciel. La méthode de gestion de projet utilisée devrait transparaître dans la documentation du processus. De plus, la documentation du processus de conception du logiciel devra mentionner les rapports générés au cours de la conception du logiciel.
On pourra également y ajouter les standards de programmation utilisés lors du processus.
Quel est le but de ce type de documentation ?
La documentation du processus est utile pour évaluer l’efficacité du processus de création d’un logiciel. Savoir que vous avez pris 120 jours pour créer un MVP pour un client vous permet de planifier vos futurs projets. Cette documentation vous permet également de savoir si vous devez toujours continuer d’utiliser le Lean Startup, Kanban ou Agile.
En second lieu, la documentation du système (System Documentation) vise à produire des documents décrivant le système conçu. Plus formellement la documentation du système est une documentation technique décrivant comment fonctionne le logiciel et comment le faire évoluer.
Enfin, la documentation de l’utilisateur (User documentation) est totalement orientée vers les utilisateurs finaux du logiciel. Les utilisateurs sont divers et ne possèdent pas les mêmes compétences. Il faudra donc « dimensionner » votre documentation de sorte que votre utilisateur puisse s’y retrouver sans peine.
La figure ci-dessus montre comment adapter sa documentation en fonction du niveau d’expertise de l’utilisateur final.
Exemple : Prenons WordPress le célèbre CMS (Content Management System). Un novice, euh un journaliste ou un blogueur par exemple voudra un manuel de prise en main simple et efficace. Par contre un développeur voudra un guide de modification du CMS pour répondre à tel ou à tel besoin (Ajouter une fonctionnalité par exemple).
Documenter, c’est bien mais à quel prix ?
Très peu de projets de conception logicielle sont documentés de façon adéquate. Enfin je crois. Par contre vous pouvez trouver des projets open source super bien documentés : Django, Symfony, …
La qualité d’une documentation est importante car si elle est bâclée, eh bien l’utilisateur est frustré lors de l’utilisateur du logiciel et se tourne vers un autre. Tant à faire une documentation, il faudrait bien la faire.
Documenter, oui comment on s’y prend en pratique ?
Ian Sommerville propose une structure pour les documentations logicielles. Libre à vous de vous y conformer. L’essentiel est de pouvoir produire un document lisible et attrayant, concret et concis. Je vous laisse lire l’article de Ian Sommerville, les détails croustillants y sont expliqués.
Documenter, oui mais quels outils utiliser ?
Le premier que je vais vous présenter est Sphinx. Je l’ai découvert grâce à une vidéo sur YouTube (Transformez votre doc Word en doc Web sous Sphinx — WEB2DAY). Je ne ferai pas une longue présentation de cet outil, mais je vous le conseille vivement.
L’autre outil (Grip un outil python pour lire les fichiers .md + Markdown un langage de balisage) permet plutôt de produire une documentation orientée développeurs. Jetez également un coup d’oeil à cette série de vidéo réalisée par Google sur Udacity.
Vous avez surement d’autre outils. Comme le choix d’un langage de programmation ou d’un framework, le choix de son outil de documentation est « un choix personnel ». Tant que vous êtes productif avec tel ou tel outil, foncez.
Documenter, oui mais à quel moment la débuter?
Un bon processus de documentation devrait débuter depuis les premières lignes de votre projet logiciel. N’attendez pas la fin de votre logiciel pour commencer à produire une documentation.
Enfin, selon moi, on devrait commencer la documentation du logiciel pendant que l’on développe ce dernier. Au cas où votre documentation ne serait pas exhaustive et parfaite, il faudra “allouer” du temps à la documentation.
J’aimerais finir ici par citer un certain nombre de documentation d’outils open source ou des API qui selon moi permettent au développeur que je suis de me sentir comme un super héro (oui, je sais j’exagère).
Tout d’abord il y a le framework qui permet de construire des applications mobiles hybrides Ionic Framework. Ensuite le framework PHP Symfony. La documentation de ces frameworks est “efficace”. Je sais où chercher quand je cherche un truc.
Récemment, par le plus grand des hasards, je suis tombé sur la documentation de PayDunya. J’apprécie beaucoup ce que les gars ont réalisé.
Tant à faire une documentation, il faudrait bien la faire.
