Il y a longtemps de cela, quand les logiciels nous étaient livrés sur disquettes, on évaluait souvent leur richesse au poids de leur manuel. Épais manuels, que bien évidemment personne n’ouvrait jamais et quand bien même on l’aurait fait, manuels où il était extrêmement difficile de trouver les informations cherchées en l’absence d’un index numérique.
Un de mes professeurs avait coutume de dire : « arrêtez de me rendre des copies sans fin, vous croyez que je note au poids ? »
Plus sérieusement, le manuel papier a quasiment disparu, et c’est tant mieux, aussi bien pour la nature que pour le confort d’utilisation que représente les PDF couramment utilisés.
Mais cette disparition a aussi entraîné comme dommage collatéral une forte réduction du volume des manuels eux-mêmes. Ainsi, si le format numérique permet une recherche rapide, très souvent le contenu ne suit plus.
Alors, dans la chaîne de production logicielle, qui doit documenter quoi pour offrir les réponses à toutes les questions que l’on peut se poser pour son exploitation quotidienne ?
Voici donc une première partie sur les documentations à destination de l’utilisateur, une seconde partie décrira les documentations techniques, internes ou externes.
Les spécifications
Commençons donc par le début : les spécifications du produit ou du fonctionnel.
C’est clairement le travail de l’architecte, de l’analyste ou du chef de projet de mettre noir sur blanc ce qu’est supposé faire sa future œuvre.
Clairement, cela ne peut pas se résumer à un rappel du cahier des charges, cela doit être une description en langage compréhensible du périmètre fonctionnel final de la solution.
Point besoin de faire un roman, ce qui est important est que l’écrit reflète un accord entre le besoin et le résultat attendu.
Les spécifications détaillées
C’est souvent là que les choses se gâtent un peu : entre la description initiale et le produit fini viennent souvent se greffer nombre de traitements et de processus distincts.
Il faut préciser point par point, les données d’entrée, les opérations effectuées, et le résultat attendu.
Nous n’en sommes pas encore à décrire comment la solution doit être utilisée, mais plutôt quel est le rôle de chacun des sous-ensembles.
Cette partie est clairement du domaine de l’acteur en charge des spécifications. Encore faut-il que le temps nécessaire soit prévu dans le délai initial.
Le manuel utilisateur
Le dinosaure de la documentation, celui qui doit tout contenir mais qui souvent ne présente que des copies d’écrans vides de sens ou en tout cas sans plus de sens que les écrans eux-mêmes, ou une litanie descriptive du contenu dédits écrans.
Oublions-le donc, car la facilité de création des interfaces actuelles, leur souplesse, et d’éventuelles aides contextuelles le remplacent facilement.
Les modes opératoires
Malgré cela, et faute d’avoir une vision globale, le traitement des cas spécifiques va nécessiter des précisions dans la documentation.
Quand l’ergonomie naturelle du logiciel ne suffit alors pas à rendre l’utilisation intuitive, quand il faut prévoir une saisie sur un écran A pour un impact sur un écran B.
C’est le mode opératoire, qui guidant l’utilisateur pas à pas, sera son sauveur.
Alors qui doit le réaliser, auteur ou acteur ?
Évidemment, chacun pense que c’est l’autre. Je reste convaincu que c’est le rôle du testeur qui a validé le fonctionnement final. Mais qui donc est le testeur, c’est une autre histoire !
À bientôt pour la seconde partie autour des documentation techniques…
Olivier Piochaud, PDG d’Apsynet
