Le C@rnet de notes

Guide de l'utilisateur - Documentation logicielle

La documentation logicielle est un texte écrit qui accompagne le logiciel informatique. Elle explique comment le logiciel fonctionne, ou comment on doit l'employer. Le terme peut avoir des significations différentes pour des personnes de différents profils.
La documentation constitue une partie importante de l'ingénierie logicielle, qui est trop souvent négligée.

Documentation sur l'architecture et la conception

La documentation sur l'architecture est un type spécial de documents de conception. D'une certaine façon, les documents sur l'architecture sont les troisièmes dérivés du code (les documents de conception étant les seconds dérivés, et documents sur le code étant le premier). Il y a très peu de chose dans les documents sur l'architecture qui soit spécifique au code lui-même. Ces documents ne décrivent pas comment programmer une fonction (routine) particulière, ou même pourquoi cette fonction particulière existe sous cette forme, mais expose les exigences générales qui motivent l'existence d'une telle fonction. Un bon document d'architecture est court sur les détails mais dense sur l'explication. Il peut suggérer des approches pour des conceptions de plus bas niveau, mais laisse les études d'exploration effectives à d'autres documents.
Une autre sorte de documents de conception est le document de comparaison. Cela peut prendre souvent la forme d'un livre blanc. Il se concentre sur un aspect spécifique du système et suggère des approches alternatives. Cela peut se situer au niveau de l'interface utilisateur, du code, de la conception, ou même au niveau de l'architecture. Il soulignera la situation du "SI" (système d'information), décrira une ou plusieurs alternives en présentant leurs avantages et inconvénients. Une bonne étude comparative est lourde en recherche, exprime ses idées clairement (sans se reposer massivement sur un jargon abscon pour aveugler le lecteur), et surtout est impartiale. Il doit expliquer honnêtement et clairement les coûts de toute solution en regard de ce qu'elle apporte de mieux. L'objectif d'une étude comparative est de discerner la meilleure solution, plutôt que de pousser à un point de vue particulier. Il est parfaitement acceptable de ne pas établir une conclusion, ou de conclure qu'aucune des alternatives n'offre d'avantage substantiel par rapport à la situation actuelle pour justifier un changement. Elle doit être conçue comme une initiative scientifique, pas comme une technique marketing.

Documentation utilisateur

À la différence de la documentation sur le code, le guide utilisateur est généralement assez éloigné du code source du programme, et décrivent simplement comment il est employé.
Dans le cas d'une bibliothèque logicielle, les documents sur le code et le guide utilisateur pourraient effectivement être couplés et cela vaut la peine de les regrouper, mais cela n'est pas toujours valable pour les applications en général.
La machine Lisp a suivi la tradition selon laquelle chaque élément de code avait un champ de documentation attaché. En relation avec les fortes capacités de recherche (basées sur une commande appropriée assimilée à Unix), et des sources en ligne, les utilisateurs de Lisp pouvaient consulter la documentation et reprendre la fonction associée directement dans leur propre code. Ce niveau de facilité est inconnu de systèmes présumés plus modernes.
Typiquement, le guide utilisateur décrit chaque caractéristique du programme, et les différentes étapes nécessaires pour l'appeler. Un bon guide utilisateur peut aussi aller jusqu'à fournir une assistance minutieuse en ligne. Il est très important que le guide utilisateur ne soient pas confus, et qu'ils soient à jour. Le guide utilisateur n'a pas besoin d'être structurés d'une façon particulière, mais il est très important qu'ils aient un index précis. La cohérence et la simplicité sont aussi deux qualités très précieuses. On considère que le guide utilisateur constitue un contrat qui spécifie ce que le logiciel doit faire. Voir aussi Technical Writing.
Il y a trois grandes manières d'organiser la documentation utilisateur :

Tutoriel

On considère qu'une approche par tutoriel est la plus utile pour un nouvel utilisateur. Dans cette méthode l'utilisateur est guidé à chaque étape d'accomplissement des tâches particulières.

Thématique

Pour un utilisateur intermédiaire, on emploie généralement une approche thématique, dans laquelle les chapitres ou sections se concentrent sur un domaine d'intérêt particulier.

Liste

Le type final de principe d'organisation est celui dans lequel les commandes ou les tâches sont simplement listées par ordre alphabétique, souvent via des indices croisés. Cette dernière approche est d'un intérêt très élevé pour des utilisateurs avancés qui connaissent exactement quelle sorte d'information ils recherchent. Un grief universellement exprimé par les utilisateurs au sujet de la documentation logicielle est qu'elle n'adopte que l'une de ces trois approches à l'exclusion des deux autres.
Dans le cas des micro-ordinateurs, il est fréquent de limiter la fourniture de documentation logicielle à l'aide en ligne, qui se limite à des informations de référence sur les commandes ou les lignes de menu. Le travail d'enseignement de nouveaux utilisateurs ou d'aide à des utilisateurs plus expérimentés à tirer le meilleur parti d'un programme est laissé à des publicateurs privés, à qui le développeur du logiciel donne une assistance significative.