Comment écrire une documentation logicielle

Une bonne documentation logicielle, qu'il s'agisse d'un document de spécifications pour les programmeurs ou testeurs, d'un document technique pour les utilisateurs ou des manuels relatifs au logiciel et des fichiers pour les utilisateurs finaux, aide l'utilisateur à comprendre les fonctionnalités et le fonctionnement du logiciel. Une bonne documentation logicielle est spécifique, concise, adéquate et apporte toutes les informations importantes à l'utilisateur du logiciel. Ci-dessous, vous trouverez des instructions qui vous expliqueront comment réaliser une documentation logicielle pour les utilisateurs techniques et finaux.

Méthode 1

Méthode 1 sur 2:

Écrire une documentation logicielle pour les utilisateurs techniques

Télécharger l'article

{"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/5\/57\/Write-Software-Documentation-Step-1.jpg\/v4-460px-Write-Software-Documentation-Step-1.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/5\/57\/Write-Software-Documentation-Step-1.jpg\/v4-728px-Write-Software-Documentation-Step-1.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}

1
Déterminez les informations qui doivent être ajoutées. Les documents de spécifications sur les logiciels servent de manuels de référence aux concepteurs de l'interface utilisateur, aux programmeurs qui créent le code et aux testeurs qui vérifient que le logiciel fonctionne comme prévu. L'information réelle dépend du programme en question, mais elle peut inclure quelques-uns des éléments suivants :
- des dossiers clés intégrés à l'application. Cela peut comporter les fichiers créés par l'équipe de conception, les données de base utilisées pendant l'exécution du programme et les programmes utilitaires tiers
- des fonctions et sous-programmes. Cela comprend une explication de ce à quoi sert chaque fonction et sous-programme, y compris ses valeurs d'entrée et de sortie
- des variables et des constantes du programme, ainsi que la façon dont elles sont utilisées sur cette application
- la structure globale du programme. Pour une application disponible sur disque, cela pourrait impliquer une description de chaque module et bibliothèque du programme, tandis que pour une application Web, cela pourrait décrire les fichiers utilisés par chaque page
{"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/6\/6f\/Write-Software-Documentation-Step-2.jpg\/v4-460px-Write-Software-Documentation-Step-2.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/6\/6f\/Write-Software-Documentation-Step-2.jpg\/v4-728px-Write-Software-Documentation-Step-2.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}

2
Décidez du nombre de documents qui devraient être inclus dans le code du programme et du nombre de documents qui ne devraient pas l'être. Plus des documents techniques sont conçus dans le code source du programme depuis le début, plus il sera facile d'actualiser et de conserver le code, ainsi que de documenter plusieurs versions de l'application originale. Au minimum, la documentation relative au code source doit expliquer le but des fonctions, des sous-programmes, des variables et des constantes.
- Si le code source est particulièrement volumineux, il peut être documenté sous forme de fichier d'aide, lequel peut être indexé ou recherché avec des mots-clés. C'est un avantage propre aux applications dont la logique de programme est fragmentée à travers plusieurs pages et comprend des fichiers supplémentaires, comme c'est le cas avec certaines applications Web.
- Certains langages de programmation comme Java et .NET Framework (Visual Basic.NET, C#) ont leurs propres normes pour ce qui est de la documentation. Dans ces cas, suivez les normes pour déterminer combien de documents doivent être inclus avec le code source.
{"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/8\/85\/Write-Software-Documentation-Step-3.jpg\/v4-460px-Write-Software-Documentation-Step-3.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/8\/85\/Write-Software-Documentation-Step-3.jpg\/v4-728px-Write-Software-Documentation-Step-3.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}

3
Choisissez l'outil de documentation adéquat. Dans certaines mesures, cela se détermine par le langage dans lequel le code est écrit, qu'il s'agisse de C++, C# , Visual Basic, Java ou PHP. En fait, des outils spécifiques existent pour ces langages et d'autres. Dans d'autres cas, l'outil adéquat est déterminé par le type de documentation nécessaire.
- Les programmes de traitement de texte de Microsoft Word sont adéquats pour créer des fichiers textes distincts de documentation, dans la mesure où la documentation est vraiment courte et simple. Pour les fichiers textes longs et complexes, plusieurs rédacteurs techniques préfèrent un outil de documentation comme Adobe FrameMaker.
- Les fichiers d'aide pour la documentation à partir d'un code source peuvent être générés avec n'importe quel outil de conception d'une aide en ligne tels que RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare ou HelpLogix.
Publicité

Méthode 2

Méthode 2 sur 2:

Écrire une documentation logicielle pour les utilisateurs finaux

Télécharger l'article

{"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/8\/85\/Write-Software-Documentation-Step-4.jpg\/v4-460px-Write-Software-Documentation-Step-4.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/8\/85\/Write-Software-Documentation-Step-4.jpg\/v4-728px-Write-Software-Documentation-Step-4.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}

1
Déterminez les motifs commerciaux de votre documentation. Bien que la raison principale d'une documentation logicielle est d'aider les utilisateurs à comprendre comment utiliser l'application, il y a aussi d'autres raisons, telles que l'aide à la commercialisation du logiciel, l'amélioration de l'image de la compagnie et plus encore, la réduction des couts d'assistance technique. Dans certains cas, la documentation est nécessaire pour se plier à certaines normes ou à d'autres exigences juridiques.
- Toutefois, la documentation logicielle ne peut en aucun cas servir à combler un désign médiocre. Si une application d'écran nécessite beaucoup de documentations pour être mieux expliquée, alors il serait mieux de changer le désign de l'écran avec quelque chose de plus intuitif.
{"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/3\/35\/Write-Software-Documentation-Step-5.jpg\/v4-460px-Write-Software-Documentation-Step-5.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/3\/35\/Write-Software-Documentation-Step-5.jpg\/v4-728px-Write-Software-Documentation-Step-5.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}

2
Comprenez les besoins du public auquel la documentation est destinée. Dans la majorité des cas, les utilisateurs de logiciel ont peu de connaissances en informatique, mis à part les taches que les applications qu'ils utilisent leur permettent de faire. Il existe plusieurs façons de déterminer comment aborder leurs besoins dans votre documentation.
- Considérez les fonctions de vos potentiels utilisateurs. Un administrateur de système est probablement un expert avec un certain nombre d'applications logicielles, tandis qu'un commis à la saisie d'informations est plus enclin à connaitre l'application qu'il ou elle utilise pour entrer les données.
- Observez les utilisateurs en question. Bien que les appellations d'emploi indiquent généralement le métier qu'exercent les gens, il peut y avoir quelques différences dans la façon dont les titres sont perçus dans une organisation. En questionnant les potentiels utilisateurs, vous aurez une idée sur la véracité ou non de leur titre d'emploi.
- Regardez la documentation existante. La documentation pour les précédentes versions du logiciel ainsi que les spécifications fonctionnelles fournissent quelques indications sur ce que l'utilisateur aura besoin de savoir pour utiliser le programme. Gardez toutefois à l'esprit que les utilisateurs finaux ne sont pas intéressés pas le fonctionnement du programme, ils sont plutôt intéressés par ce que le programme peut leur apporter.
- Identifiez les tâches nécessaires pour exécuter le travail et ce qu'il faut faire au préalable avant ces dernières.
{"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/5\/5b\/Write-Software-Documentation-Step-6.jpg\/v4-460px-Write-Software-Documentation-Step-6.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/5\/5b\/Write-Software-Documentation-Step-6.jpg\/v4-728px-Write-Software-Documentation-Step-6.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}

3
Déterminez le format approprié pour la documentation. La documentation logicielle peut être structurée en 1 ou 2 formats, le manuel de référence et le guide de l'utilisateur. Parfois, une combinaison des formats est la meilleure approche.
- Un manuel de référence est destiné à expliquer chacune des fonctionnalités d'une application logicielle (bouton, onglet, champ, boite de dialogue) et leur fonctionnement. Plusieurs fichiers d'aide sont écrits dans ce format, en particulier l'aide contextuelle qui affiche un sujet pertinent chaque fois que l'utilisateur clique sur le bouton d'aide sur un écran quelconque.
- Un guide d'utilisateur explique comment utiliser le logiciel pour réaliser une tâche particulière. Les guides d'utilisateur viennent souvent sous des formats de guides imprimés ou en format PDF, bien que certains fichiers d'aide comprennent des sujets pour réaliser une tâche particulière. (Ces sujets ne sont généralement pas contextuels, bien qu'ils puissent être liés par des liens hypertextes à des sujets qui le sont.) Les guides d'utilisateur prennent souvent la forme des tutoriels, avec un résumé des tâches à réaliser dans l'introduction et les instructions fournies en plusieurs étapes.
{"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/d\/d9\/Write-Software-Documentation-Step-7.jpg\/v4-460px-Write-Software-Documentation-Step-7.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/d\/d9\/Write-Software-Documentation-Step-7.jpg\/v4-728px-Write-Software-Documentation-Step-7.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}

4
Décidez de la forme que la documentation devrait prendre. La documentation logicielle pour les utilisateurs finaux peut prendre une ou plusieurs formes : manuels imprimés, documents PDF, fichiers d'aide ou assistance en ligne. Chacune de ces formes est conçue pour montrer à l'utilisateur comment utiliser les fonctions du programme. Que ce soit sous forme de tutoriel ou d'un aperçu, dans le cas des fichiers d'aide et d'assistance en ligne, cela peut inclure des vidéos de démonstration ainsi que des textes et bien sûr des graphismes.
- Les fichiers d'aide et d'assistance en ligne devraient être indexés et équipés d'une fonctionnalité pour permettre aux utilisateurs de rapidement trouver l'information qu'ils recherchent par des mots-clés. Bien que les logiciels de conception de fichier d'aide puissent automatiquement générer les index, il est souvent mieux de créer l'index de façon manuelle, en utilisant des termes que les utilisateurs sont plus susceptibles de rechercher.
{"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/f\/fd\/Write-Software-Documentation-Step-8.jpg\/v4-460px-Write-Software-Documentation-Step-8.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/f\/fd\/Write-Software-Documentation-Step-8.jpg\/v4-728px-Write-Software-Documentation-Step-8.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}

Les guides d'utilisation imprimés ou PDF peuvent être écrits avec un programme de traitement de texte comme Word ou un éditeur de texte sophistiqué comme FrameMaker, en fonction de leur longueur et de la complexité. Les fichiers d'aide peuvent être écrits avec un outil de conception d'une aide en ligne comme RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix ou HelpServer.

Publicité