Documentation logicielle
Ladocumentation logicielleest un texte, généralement accompagné de captures d'écran, qui concerne un logicielinformatique.Elle explique comment le logiciel fonctionne, et/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 souvent négligée[réf. nécessaire].
Types de documentation
[modifier|modifier le code]La documentation peut être de plusieurs types:
- L'expression de besoin - Définit le besoin du métier lors d'une demande.
- Architecture / Conception - Vue d'ensemble sur le logiciel. Elle inclut les relations à l'environnement et les principes à utiliser dans la conception et la réalisation des composants logiciels.
- Technique - Documentation ducode,algorithmes, interfaces, etinterfaces de programmation(API).
- Utilisateur - Manuels pour les utilisateurs, administrateurs systèmes et personnel de support.
- Marketing - Instructions sur le produit et garantie promotionnelle.
Expression de besoin
[modifier|modifier le code]Documentation sur l'architecture et la conception
[modifier|modifier le code]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 unefonction(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'unlivre 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 alternatives 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 unjargonabscons 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 de phrases
[modifier|modifier le code]S'agissant de la documentation technique, il convient de distinguer plusieurs types de documentation:
- la documentation associée aulogiciel d'exploitation,qui fournit à l'exploitant les instructions d'utilisation dumaté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 desprogrammeursemploient l'expression « documentation logicielle » dans le cas d'une documentation sur leslogiciels d'application.Lorsqu'ils développent dulogiciel,lecode sourceest 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 afin d'être facilement accessible à quiconque serait amené à le parcourir.
Ce document écrit peut être hautement technique, et il est principalement utilisé pour définir et expliquer lesinterfaces de programmation(APIs), les structures de données et lesalgorithmes.Par exemple, on peut utiliser cette documentation pour expliquer que la variablem_namese 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 lesgénérateurs de documentationcommeSphinx,DoxygenouJavadocpeuvent être utilisés pour générer automatiquement la documentation ducode sourcedu logiciel; ils extraient lescommentairesdu code source et créent des manuels de référence au formatHTMLouPDF.Les documents générés sont souvent organisés dans le style d'unguide de référence,ce qui permet à un programmeur de localiser rapidement une fonction ou une classe quelconque.
Beaucoup deprogrammeursapprécient la documentation automatique du code source, particulièrement parce qu'elle lui permet de l'écrire en se référant à son code et d'utiliser les mêmes outils que pour écrire le code. Cela facilite la synchronisation entre le code source et la documentation.
L'inconvénient est que seuls lesprogrammeurspeuvent éditer ce type de documentation, et c'est d'eux que dépend la mise à jour des sorties (par exemple, en exécutant uncrontabpour mettre à jour les documents la nuit). Certains considèrent cela comme un avantage plutôt que comme un inconvénient.
Donald Knutha insisté sur le fait que la documentation peut être un processus très difficile de réflexion après coup et a recommandé laprogrammation lettrée,qui consiste à écrire la documentation en même temps et même endroit que le code source et à l'extraire par des moyens automatiques.
Documentation utilisateur
[modifier|modifier le code]À la différence de la documentation technique, 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'unebibliothè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.
Lamachine Lispa 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 unindexpré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.
Il y a trois grandes manières d'organiser la documentation utilisateur:
- Tutoriel
- On considère qu'une approche partutorielest la plus utile pour un nouvel utilisateur. Dans cette méthode l'utilisateur est guidé à chaque étape d'accomplissement des tâches particulières à l'aide de captures d'écran et d'instructions.
- 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 desmicro-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
[modifier|modifier le code]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:
- Inciter les utilisateurs potentiels à s'intéresser au produit et installer le désir de s'impliquer davantage dans le produit.
- 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.
- Expliquer la position de ce produit par rapport à d'autres alternatives.
Une bonne technique de marketing est de fournir des phrases d'accrocheclaires 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
[modifier|modifier le code]Cycle de vie du logiciel
[modifier|modifier le code]- Architecture:cadre d'architecture(Cadre Zachman,TOGAF,DoDAF,MODAF,AGATE)
- Conception:UML,SysML,BPML...
- Réalisation:BPEL...
Génie logiciel et documentation
[modifier|modifier le code]Emploi de la langue française
[modifier|modifier le code]
Dans le cas où il y a uncontratavec unconsommateur,et pour tout organisme régi par la loi française, laloi relative à l'emploi de la langue françaises'applique (loi communément appeléeloi Toubon,1994).
En1996,une circulaire précisait que le mode d'emploi des logiciels d'application et d'exploitation devait être rédigé enfrançais.
Les licences de logiciel peuvent être plus ou moins conçues en fonction des besoins de documentation logicielle.
Cas de fourniture dematériel informatique
[modifier|modifier le code]La fourniture dematériel informatiqueest habituellement assortie de la fourniture de la documentation logicielle associée qui indique au personnel exploitant les instructions qui permettent d'employer lematériel informatique.
La licenceGNU/FDLde laFree Software Foundationa été pensée et créée pour la documentation associée aulogiciel,elle est très largement utilisée pour la documentation dulogiciel 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.
Contrôles d'application de la loi
[modifier|modifier le code]C'est laDGCCRFqui 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.
