Après la partie client, abordons le détail de ce qui devrait être fourni par les équipes de développement et de mise en œuvre des solutions. On va parler ici de documentations techniques qui sont destinées d’abord à leur propre usage, pour mémoire, pour la maintenabilité de la solution, et cela bien sûr à tous les niveaux du processus.
La documentation est l’assurance-vie du logiciel
C’est elle qui garantit les possibilités de maintenance, c’est-à-dire de revenir sur un élément pour le faire évoluer, le débugger mais aussi pour expliquer son comportement selon les données qui lui sont soumises.
On imagine bien que pour le coup il y a de multiples couches, de multiples acteurs, lesquels en outre peuvent changer durant le cours de la vie de la solution.
Parcourons donc les différents éléments de documentation technique qu’il faut traiter dans une solution logicielle.
La documentation du code source
Tout d’abord au premier niveau, commenter son code source peut sembler inutile aux développeurs. Mais je vous garantis que relire du code sans le moindre commentaire et à la fois pénible et le plus souvent inefficace, y compris pour celui qui l’a écrit.
Le commentaire commence donc par choisir des noms de variables ou de fonctions ou de classes avec un sens suffisant, quitte à ce que ces noms soient long. Mais c’est évidemment aussi des phrases expliquant le propos exact d’un ensemble de codes et l’utilisation des éventuels paramètres.
La documentation du modèle de données
Le plus souvent les logiciels stockent des données, dans des bases du même nom, et pour cela ils utilisent des tables, liées les unes aux autres. Tous les SGBD aujourd’hui permettent de générer automatiquement ce que l’on appelle un modèle conceptuel de données, mais cela ne dispense clairement pas d’en expliquer la structure et les relations.
La documentation d’installation
Chaque mise en œuvre est différente de la précédente, le contexte d’installation, les systèmes d’exploitation et de base de données, les ordinateurs impliqués clients ou serveurs, l’architecture réseau. Tous ces éléments nécessitent d’expliquer et de noter les choix faits, les paramètres, les noms utilisés et éventuellement les codes d’accès.
La documentation d’exploitation
Une fois la solution opérationnelle, il faut toujours prévoir la possibilité d’une panne, ou même tout simplement les outils de diagnostic pour anticiper les pannes ou traiter des problèmes de performances.
Cela doit faire l’objet d’une documentation de maintien en condition opérationnelle afin de garantir l’autonomie de l’exploitant dans l’utilisation au quotidien de la solution.
On y trouvera les informations sur les journaux de fonctionnement ou d’erreurs, des processus de diagnostic, éventuellement les solutions correctives à mettre en œuvre.
C’est aussi là que l’on trouvera le mode opératoire de sauvegarde et celui de redémarrage.
La documentation de réversibilité
Le dernier point à documenter est celui qui concerne la fin de vie de la solution, notamment en matière de reprise des données et est accessoirement pour sa désinstallation.
Pour le premier sujet, en règle générale, cette partie décrit les méthodes d’accès direct aux données soit depuis la base de données soit éventuellement depuis un Web service ou pire par l’export de fichiers textes.
Olivier Piochaud, PDG d’Apsynet
