Une bonne documentation logicielle, qu'il s'agisse de documentation de spécifications pour les programmeurs et les testeurs, de documents techniques pour les utilisateurs internes ou de manuels et fichiers d'aide pour les utilisateurs finaux, aidera les utilisateurs à comprendre les caractéristiques et les fonctions du logiciel. Une bonne documentation est une documentation spécifique, claire et pertinente, contenant toutes les informations dont l'utilisateur a besoin. Cet article vous guidera dans la rédaction de la documentation du logiciel pour les utilisateurs techniques et les utilisateurs finaux.
Étape
Méthode 1 sur 2: Rédaction de la documentation logicielle pour les utilisateurs techniques
Étape 1. Sachez quelles informations inclure
Le document de spécification est utilisé comme manuel de référence pour les concepteurs d'interfaces, les programmeurs qui écrivent du code et les testeurs qui vérifient les performances du logiciel. Les informations qui doivent être incluses dépendent du programme en cours de création, mais peuvent inclure les éléments suivants:
- Les fichiers importants de l'application, tels que les fichiers créés par l'équipe de développement, les bases de données accessibles pendant l'exécution du programme et les applications tierces.
- Fonctions et sous-programmes, y compris une explication de l'utilisation de la fonction/du sous-programme, des valeurs d'entrée et de sortie.
- Variables et constantes du programme, et comment elles sont utilisées.
- Structure globale du programme. Pour les programmes basés sur un lecteur, vous devrez peut-être décrire chaque module et bibliothèque. Ou, si vous écrivez un manuel pour un programme Web, vous devrez peut-être expliquer quels fichiers chaque page utilise.
Étape 2. Décidez quel niveau de documentation doit être présent et séparable du code du programme
Plus la documentation technique est incluse dans le code du programme, plus il sera facile de la mettre à jour et de la maintenir, ainsi que d'expliquer les différentes versions du programme. Au minimum, la documentation dans le code du programme doit inclure l'utilisation de fonctions, de sous-programmes, de variables et de constantes.
- Si votre code source est long, vous pouvez écrire de la documentation dans un fichier d'aide, qui peut ensuite être indexé ou recherché avec certains mots-clés. Des fichiers de documentation séparés sont utiles si la logique du programme est répartie sur plusieurs pages et comprend des fichiers de support, comme une application Web.
- Certains langages de programmation (tels que Java, Visual Basic. NET ou C#) ont leurs propres normes de documentation de code. Dans de tels cas, suivez la documentation standard qui doit être incluse dans le code source.
Étape 3. Sélectionnez l'outil de documentation approprié
Dans certains cas, l'outil de documentation est déterminé par le langage de programmation utilisé. Les langages C++, C#, Visual Basic, Java, PHP, et autres ont leurs propres outils de documentation. Cependant, si ce n'est pas le cas, les outils utilisés dépendront de la documentation requise.
- Un traitement de texte tel que Microsoft Word convient à la création de fichiers texte de documents, à condition que la documentation soit concise et simple. Pour créer une longue documentation avec du texte complexe, la plupart des rédacteurs techniques choisissent un outil de documentation spécialisé, tel qu'Adobe FrameMaker.
- Les fichiers d'aide pour documenter le code source peuvent être créés avec un programme de génération de fichiers de support, 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
Étape 1. Connaître les raisons commerciales qui sous-tendent la création du manuel
Alors que la principale raison de la documentation du logiciel est d'aider les utilisateurs à comprendre comment utiliser l'application, il existe plusieurs autres raisons qui peuvent sous-tendre la création de la documentation, comme aider le service marketing à vendre l'application, améliorer l'image de l'entreprise et réduire le support technique. frais. Dans certains cas, la documentation est requise pour se conformer à la réglementation ou à d'autres exigences légales.
Cependant, la documentation n'est pas un bon substitut à une interface. Si une application nécessite beaucoup de documentation pour fonctionner, elle doit être conçue pour être plus intuitive
Étape 2. Connaître le public cible de la documentation
Généralement, les utilisateurs de logiciels ont des connaissances informatiques limitées au-delà des applications qu'ils utilisent. Il existe plusieurs façons de répondre à leurs besoins en matière de documentation:
- Faites attention au titre de l'utilisateur du logiciel. Par exemple, l'administrateur système comprend généralement diverses applications informatiques, tandis que le secrétaire ne connaît que les applications qu'il utilise pour saisir des données.
- Faites attention aux utilisateurs de logiciels. Bien que leurs postes soient généralement compatibles avec les tâches exécutées, ces postes peuvent avoir des charges de travail différentes, selon le lieu d'affaires. En interrogeant des utilisateurs potentiels, vous pouvez savoir si votre évaluation de leur intitulé de poste est correcte.
- Faites attention à la documentation existante. La documentation et les spécifications des fonctionnalités du logiciel peuvent montrer ce que les utilisateurs doivent savoir pour les utiliser. Cependant, gardez à l'esprit que les utilisateurs peuvent ne pas être intéressés à connaître les « entrailles » du programme.
- Sachez ce qu'il faut pour accomplir une tâche et ce qu'il faut avant de pouvoir l'accomplir.
Étape 3. Déterminez le format approprié pour la documentation
La documentation du logiciel peut être organisée en 1 ou 2 formats, à savoir des livres de référence et des manuels. Parfois, combiner les deux formats est une bonne solution.
- Les formats de référence sont utilisés pour décrire toutes les fonctionnalités du logiciel, telles que les boutons, les onglets, les champs et les boîtes de dialogue, et leur fonctionnement. Certains fichiers d'aide sont écrits dans ce format, en particulier ceux qui sont contextuels. Lorsque l'utilisateur clique sur Aide dans un certain écran, l'utilisateur recevra le sujet correspondant.
- Le format manuel est utilisé pour expliquer comment faire quelque chose avec le logiciel. Les manuels sont généralement au format papier ou PDF, bien que certaines pages d'aide incluent également des instructions sur la façon de faire certaines choses. (En général, les formats manuels ne sont pas contextuels, mais peuvent être liés à des sujets contextuels). Les manuels se présentent généralement sous la forme d'un guide, avec un résumé des tâches à effectuer dans un descriptif et un guide formaté par étapes.
Étape 4. Décidez du type de documentation
La documentation du logiciel pour les utilisateurs peut être fournie dans un ou plusieurs des formats suivants: manuels imprimés, fichiers PDF, fichiers d'aide ou aide en ligne. Chaque type de documentation est conçu pour vous montrer comment utiliser les fonctions du logiciel, qu'il s'agisse d'un guide ou d'un tutoriel. La documentation en ligne et les pages d'aide peuvent également inclure des vidéos de démonstration, du texte et des images statiques.
Les fichiers d'aide et de support en ligne doivent être indexés et consultables à l'aide de mots-clés afin que les utilisateurs puissent rapidement trouver les informations dont ils ont besoin. Bien qu'une application génératrice de fichiers d'aide puisse créer un index automatiquement, il est toujours recommandé de créer un index manuellement à l'aide des mots-clés fréquemment recherchés
Étape 5. Sélectionnez l'outil de documentation approprié
Les manuels imprimés ou les PDF peuvent être créés avec un programme de traitement de texte tel que Word ou un éditeur de texte avancé tel que FrameMaker, selon la longueur et la complexité du fichier. Les fichiers d'aide peuvent être écrits avec un programme de création de fichiers d'aide, tel que RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix ou HelpServer.
Des astuces
- Le texte de la documentation du programme doit être structuré de manière à être facile à lire. Placez l'image aussi près que possible du texte approprié. Décomposez la documentation par sections et sujets de manière logique. Chaque section ou sujet doit décrire un problème spécifique, à la fois la tâche et les caractéristiques du programme. Les problèmes connexes peuvent être expliqués avec des liens ou des listes de références.
- Chacun des outils de documentation décrits dans cet article peut être complété par un programme de création de captures d'écran, tel que SnagIt si votre documentation nécessite plusieurs captures d'écran. Comme toute autre documentation, vous devez également inclure des captures d'écran pour expliquer le fonctionnement de l'application, plutôt que de « leurrer » l'utilisateur.
- Il est très important de prêter attention au style, surtout si vous écrivez de la documentation logicielle pour les utilisateurs finaux. Adressez-vous aux utilisateurs avec le pronom "vous", au lieu de "utilisateur".
