Documentation Logicielle

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.

Types de documentation

La documentation peut être de plusieurs types :

• Architecture / Conception - Vue d'ensemble sur le logiciel. Elle inclut les relations à l'environment et les principes à utiliser dans la conception et la réalisation des composants logiciels.
• Technique - Documentation du code, algorithmes, interfaces, et interfaces de programmation (API).
• Utilisateur - Manuels pour les utilisateurs, administrateurs systèmes et personnel de support.
• Marketing - Instructions sur le produit et garantie promotionnelle.

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 technique

S'agissant de la documentation technique, il convient de distinguer plusieurs types de documentation :

• la documentation associée au logiciel d'exploitation, qui fournit à l'exploitant les instructions d'utilisation du matériel informatique (ordinateur) ;
• la documentation associée aux logiciels d'application (grandes fonctions de l'entreprise : finances, achats, logistique,...), qui indique comment utiliser le logiciel.

La plupart des programmeurs emploient l'expression " documentation logicielle " dans le cas d'une documentation sur les logiciels d'application. Lorsqu'ils développent du logiciel, le code source est insuffisant à lui seul. Il doit y avoir du texte qui l'accompagne pour décrire les différents aspects du fonctionnement attendu. Cette documentation est habituellement incluse dans le code source lui-même de telle sorte qu'elle soit facilement accessible à quiconque qui serait amené à le traverser.

Ce document écrit peut être hautement technique, et il est principalement utilisé pour définir et expliquer les interfaces de programmation (APIs), les structures de données et les algorithmes. Par exemple, on peut utiliser cette documentation pour expliquer que la variable m_name se réfère au premier et au dernier nom d'une personne. Il est important pour les documents sur le code d'être précis, mais pas non plus verbeux à un point tel qu'il serait difficile de le maintenir.

Souvent, des outils comme Doxygen, javadoc, ROBODoc, MakeDoc, POD ou TwinText peuvent être utilisés pour générer automatiquement le document sur le code ; ils extraient le commentaire du code source et créent des manuels de référence sous des formes comme le texte ou des fichiers HTML. Les documents sur le code sont souvent organisés dans le style d'un guide de référence, ce qui permet à un programmeur de localiser rapidement une fonction ou une classe quelconque.

Beaucoup de programmeurs aiment réellement l'idée de la documentation générée automatiquement pour diverses raisons. Par exemple, parce qu'elle est extraite du code source lui-même (par exemple, à travers les commentaires), le programmeur peut l'écrire en se référant à son code, et peut utiliser les mêmes outils que ceux qu'il a utilisés pour développer le code source, pour faire la documentation. Cela rend beaucoup plus facile la mise à jour de la documentation.

Bien sûr, l'inconvénient est que seuls les programmeurs peuvent éditer cette sorte de documentation, et c'est d'eux que dépend la mise à jour des sorties (par exemple, en exécutant un crontab pour mettre à jour les documents la nuit). Certains pourraient caractériser cela comme un avantage plutôt que comme un inconvénient.

Donald Knuth a insisté sur le fait que la documentation peut être un processus très difficile de réflexion après coup et a recommandé la programmation lettrée, qui consiste à écrire la documentation en même temps et en un même lieu que le code source et à l'extraire par des moyens automatiques.

Documentation utilisateur

À la différence de la documentation sur le code, les documents utilisateurs sont généralement assez éloignés 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 les documents utilisateurs 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, la documentation utilisateurs décrit chaque caractéristique du programme, et les différentes étapes nécessaires pour l'appeler. Un bon document utilisateur peut aussi aller jusqu'à fournir une assistance minutieuse en ligne. Il est très important que les documents utilisateurs ne soient pas confus, et qu'ils soient à jour. Les documents utilisateurs n'ont 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 la documentation 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.

Documentation marketing

Pour beaucoup d'applications, il est nécessaire de disposer de matériaux promotionnels pour inciter des observateurs occasionnels à passer plus de temps à s'intéresser au produit.

Cette forme de documentation a trois objectifs :

1. Inciter les utilisateurs potentiels à s'intéresser au produit et installer le désir de s'impliquer davantage dans le produit.
2. Informer l'utilisateur sur ce que fait exactement le produit, de telle sorte que leurs attentes soient en phase avec ce qu'ils vont recevoir.
3. Expliquer la position de ce produit par rapport à d'autres alternatives.

Une bonne technique de marketing est de fournir des phrases d'accroche claires et mémorisables qui illustrent le point que l'on souhaite transmettre, et aussi mettre l'accent sur l'interopérabilité du programme avec d'autres produits.

Outils et méthodes

Cycle de vie du logiciel

• Architecture : cadre d'architecture (Cadre Zachman, DoDAF, MODAF, AGATE)
• Conception : UML, SysML, BPML,...
• Réalisation : BPEL,...

Génie logiciel et documentation

• Programmation lettrée

Emploi de la langue française

Dans le cas où il y a un contrat avec un consommateur, et pour tout organisme régi par la loi française, la loi relative à l'emploi de la langue française s'applique (loi communément appelée loi Toubon, 1994).

En 1996, une circulaire précisait que le mode d'emploi des logiciels d'application et d'exploitation devait être rédigé en français.

Les licences de logiciel peuvent être plus ou moins conçues en fonction des besoins de documentation logicielle.

Cas de fourniture de matériel informatique

La fourniture de matériel informatique est habituellement assortie de la fourniture de la documentation logicielle associée qui indique au personnel exploitant les instructions qui permettent d'employer le matériel informatique.

Cas du logiciel libre

La licence GNU/FDL de la Free Software Foundation a été pensée et créée pour la documentation associée au logiciel, elle est très largement utilisée pour la documentation du logiciel libre, mais pas uniquement.

La cession de droits (concrétisée par une licence) est un contrat au sens juridique, la loi Toubon s'applique dans la mesure où l'organisme est régi par la loi française.

Pour plus de détails : Licences des documents libres sur documentlibre.org

Contrôles d'application de la loi

C'est la DGCCRF qui est chargée de procéder aux contrôles d'application de la loi. La Commission des affaires culturelles demande à ce qu'une circulaire puisse apporter « les clarifications nécessaires à la bonne application de la loi sur l'emploi de la langue française dans l'univers numérique », notamment pour pouvoir renforcer le cadre dans lequel doivent s'inscrire les contrôles de la DGCCRF.

Voir aussi

• (fr) Programmation par contrat
• (fr) Rédacteur de documentation
• (en) Comparaison of documentation generators
• (en) Docstring

Ce document provient de « Documentation logicielle ».