Comment rédiger de la documentation pour un logiciel : 8 étapes (avec des images)

Teneur

Pas
- Méthode 1 sur 2: Rédaction de la documentation du logiciel pour les utilisateurs techniques
- Méthode 2 sur 2: Rédaction de la documentation logicielle pour les utilisateurs finaux
Des astuces
Nécessités

Une bonne documentation logicielle, qu`il s`agisse d`un document de spécifications pour les programmeurs et les testeurs, d`un document technique pour les collègues ou de manuels de logiciels et de fichiers d`aide pour les utilisateurs finaux, aide la personne qui doit travailler avec le logiciel à comprendre toutes ses fonctionnalités et fonctions. Une bonne documentation logicielle est spécifique, concise et pertinente, fournissant toutes les informations importantes à la personne utilisant le logiciel. Vous trouverez ci-dessous des instructions sur la rédaction de la documentation du logiciel pour les utilisateurs techniques et les utilisateurs finaux.

Pas

Méthode 1 sur 2: Rédaction de la documentation du logiciel pour les utilisateurs techniques

Image intitulée Write Software Documentation Step 1

1. Décidez des informations à inclure. Les spécifications du logiciel servent de guides pour les concepteurs d`interface utilisateur, les programmeurs qui écrivent le code et les testeurs qui vérifient que le logiciel fonctionne comme prévu. Les informations exactes dépendent du programme en question, mais peuvent inclure l`un des éléments suivants :

Les fichiers les plus importants de l`application. Il peut s`agir de fichiers créés par l`équipe de développement, de bases de données accessibles pendant le fonctionnement du programme et d`utilitaires tiers.
Fonctions et sous-programmes. Cela inclut une explication de ce que fait chaque fonction ou sous-routine, y compris toutes les valeurs d`entrée et de sortie.
Variables et constantes du programme, et comment elles sont utilisées dans l`application.
La structure générale du programme. Pour une application sur disque, cela pourrait être une description des modules et bibliothèques individuels du programme, tandis que pour une application Web, cela pourrait décrire quelles pages utilisent quels fichiers.

Image intitulée Write Software Documentation Step 2

2. Décidez quelle quantité de documentation doit être incluse dans le code du programme et quelle quantité doit être conservée séparément. Plus la documentation technique a déjà été développée dans le code source du programme, plus il sera facile de la mettre à jour et de la maintenir avec le code, ainsi que de documenter les différentes versions de l`application d`origine. Au minimum, la documentation dans le code source doit expliquer le but des fonctions, des sous-programmes, des variables et des constantes.

Si le code source est particulièrement long, il peut être documenté sous la forme d`un fichier d`aide, indexable et interrogeable par mots-clés. C`est un avantage particulier pour les applications où la logique du programme est fragmentée sur de nombreuses pages et contient un certain nombre de fichiers supplémentaires, comme avec certaines applications Web.

Certains langages de programmation, tels que Java et .NET Framework (Visual Basic.NET, C#), ont leurs propres normes pour documenter le code. Dans ces cas, suivez les normes sur la quantité de documentation à inclure dans le code source.

Image intitulée Write Software Documentation Step 3

3. Choisissez le bon outil de documentation. Dans une certaine mesure, cela est déterminé par le langage dans lequel le code est écrit (tel que C++, C#, Visual Basic, Java ou PHP), car des outils spécifiques existent pour ces langages et d`autres. Dans d`autres cas, le type de documentation requise détermine quel outil utiliser.

Les programmes de traitement de texte pour Microsoft Word sont suffisants pour créer des fichiers texte séparés pour la documentation, tant que la documentation est assez courte et simple. Pour les fichiers texte longs et complexes, de nombreux rédacteurs techniques préfèrent un outil de documentation comme Adobe FrameMaker.

Les fichiers d`aide pour documenter le code source peuvent être produits avec n`importe quel outil de création d`aide, tel que RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare ou HelpLogix.

Méthode 2 sur 2: Rédaction de la documentation logicielle pour les utilisateurs finaux

Image intitulée Write Software Documentation Step 4

1. Déterminez les raisons commerciales de votre documentation. Alors que la raison fonctionnelle de la documentation du logiciel est d`aider les utilisateurs à comprendre comment utiliser l`application, il existe d`autres raisons telles que l`aide à la commercialisation du logiciel, l`amélioration de l`image de l`entreprise et, surtout, la réduction des coûts de support technique. Dans certains cas, la documentation est nécessaire pour se conformer à certaines réglementations ou à d`autres exigences légales.

Cependant, la documentation du logiciel ne doit en aucun cas se substituer à une mauvaise conception de l`interface. Si une application nécessite des pages de documentation comme guide, il est préférable de changer la conception de l`écran pour quelque chose de plus intuitif.

Image intitulée Write Software Documentation Step 5

2. Comprendre le public pour lequel vous écrivez la documentation. Dans la plupart des cas, les utilisateurs de logiciels ont peu de connaissances sur les ordinateurs au-delà des tâches qu`ils peuvent effectuer avec les applications qu`ils utilisent. Il existe plusieurs façons de déterminer ce dont ils ont besoin et comment votre documentation peut y répondre.

Regardez les fonctionnalités de vos utilisateurs potentiels. Un administrateur système est susceptible d`être un expert sur un certain nombre d`applications logicielles, tandis qu`un commis à la saisie de données est susceptible de ne connaître que l`application qu`il utilise pour saisir des données.

Regardez les utilisateurs eux-mêmes. Alors que les titres de poste indiquent généralement ce que font les gens, il peut y avoir des différences significatives dans la façon dont certains postes sont pourvus au sein d`une organisation. En interrogeant des utilisateurs potentiels, vous pouvez vous faire une idée si votre impression de ce que leur position indique est correcte ou non.

Consulter la documentation existante. La documentation des versions précédentes du logiciel (ainsi que les spécifications fonctionnelles) fournit une indication de ce que l`utilisateur doit savoir pour utiliser le programme. Cependant, gardez à l`esprit que les utilisateurs finaux ne sont pas vraiment intéressés par le fonctionnement du programme, mais par ce qu`il peut faire pour eux.

Déterminer les tâches qui doivent être effectuées pour terminer une mission, et quelles tâches doivent être effectuées avant que ces tâches puissent être effectuées.

Image intitulée Write Software Documentation Step 6

3. Déterminer le format correct pour la documentation. La documentation du logiciel peut être structurée dans 1 des 2 formats : le manuel et le manuel d`utilisation. Parfois, une combinaison des deux formats est la meilleure approche.

Un guide de référence est consacré à expliquer les différentes fonctions d`une application logicielle (boutons, onglets, champs et boîte de dialogue) et leur fonctionnement. De nombreux fichiers d`aide sont écrits dans ce format, en particulier l`aide contextuelle qui affiche un sujet pertinent lorsqu`un utilisateur clique sur le bouton Aide sur un écran particulier.

Un guide de l`utilisateur explique comment utiliser le logiciel pour effectuer une tâche particulière. Les manuels d`utilisation sont souvent formatés sous forme de guides imprimés ou de fichiers PDF, bien que certains fichiers d`aide contiennent des rubriques sur la façon d`effectuer certaines tâches. (Ces rubriques d`aide ne dépendent généralement pas du contexte, bien qu`elles puissent être liées à des rubriques qui sont.) Les guides utilisateurs se présentent souvent sous forme de tutoriels, avec un aperçu des tâches à effectuer en introduction et des instructions données par étapes numérotées.

Image intitulée Write Software Documentation Step 7

4. Décidez de la forme que doit prendre la documentation. La documentation du logiciel peut prendre plusieurs formes : manuels, documents PDF, fichiers d`aide ou aide en ligne. Chaque formulaire est conçu pour montrer à l`utilisateur l`utilisation de chacune des fonctionnalités du programme, que ce soit sous la forme d`une procédure pas à pas ou d`un tutoriel ; dans le cas des fichiers d`aide et de l`aide en ligne, cela peut être aussi bien du texte que des vidéos de démonstration ainsi que des images.

Les fichiers d`aide et l`aide en ligne doivent être indexés et consultables avec des mots-clés, permettant aux utilisateurs de trouver rapidement les informations dont ils ont besoin. Alors que les constructeurs de fichiers d`aide peuvent générer automatiquement des index, il est souvent préférable de créer l`index manuellement, en utilisant des termes que les utilisateurs rechercheront généralement.

Image intitulée Write Software Documentation Step 8

5. Choisir un outil de documentation adapté. Les manuels imprimés ou PDF peuvent être écrits à l`aide d`un programme de traitement de texte tel que Word ou d`un éditeur de texte avancé tel que FrameMaker, en fonction de leur longueur et de leur complexité. Les fichiers d`aide peuvent être écrits avec un outil de création spécial tel que RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix ou HelpServer.

Des astuces

Le texte doit être organisé pour être facile à lire, avec des images aussi proches que possible du texte auquel il se réfère. Divisez la documentation de manière logique en paragraphes, sections et sujets. Chaque paragraphe ou sujet doit expliquer un seul problème, qu`il s`agisse d`une fonction de programme ou d`une tâche. Les problèmes connexes peuvent être expliqués, le cas échéant, à l`aide des listes ou des hyperliens « Voir aussi » comme indiqué ci-dessus.
Tous les outils de documentation répertoriés ci-dessus peuvent être complétés par un programme de capture d`écran, tel que Snagit, si la documentation nécessite des captures d`écran. Comme pour toute autre documentation, des captures d`écran doivent être incluses pour aider à expliquer le fonctionnement du logiciel, pour ne pas embrouiller l`utilisateur.
Le ton est très important, en particulier lors de la rédaction de la documentation du logiciel pour les utilisateurs finaux. Adressez les utilisateurs à la deuxième personne ("vous") au lieu de la troisième personne ("utilisateur").