Méthodes et mécanique de la création d’une Documentation utilisateur fiable

Original: http://www.praxagora.com/andyo/professional/reliable.html


Ce document a été préparé pour et présenté à la Conférence de qualité logiciel 1991 du Nord-Ouest du Pacifique.
Copyright © 1991 Andrew Oram
Résumé
La documentation utilisateur, longtemps considérée comme une responsabilité importune pour les équipes de projet logiciel, effectivement réalisable avec les mêmes processus de spécification, l’examen et mesure comme les autres livrables dans un système informatique. Cet article décrit une méthode pratique, peu coûteuse que certains fournisseurs informatiques commerciaux ont utilisé pour créer et réviser leurs manuels. Il emploie une forme simple de spécification constructive afin de déterminer les opérations valides que les utilisateurs peuvent effectuer. La méthode conduit à un ensemble de modèles d’utilisation et une série d’exemples qui peuvent être intégrés dans les tests de régression automatique. Avantages comprennent mieux documentées des besoins environnementaux tels que les conditions préalables et des restrictions, des liens évidents entre les tâches de l’utilisateur et des caractéristiques du produit, et automatique régulier vérifie sur l’exactitude du document.

Le domaine du logiciel est depuis longtemps une attitude ambivalente envers la documentation utilisateur. Programmeurs et personnel d’Assurance de la qualité certainement apprécie quand un bon manuel aide à en savoir plus sur leurs propres projets. Et dans les ouvrages de génie logiciel, on aurait des difficultés à trouver un texte qui ne parvient pas à la documentation utilisateur de liste comme un livrable. Mais en revanche, ingénieurs ne se sentent pas à l’aise avec les spécifications et les évaluations dans le domaine de la documentation de l’utilisateur. Ainsi, beaucoup il relèguent la frange de leurs projets, parfois en le clouant sur à la dernière minute. Ironiquement, la tendance dans la littérature de génie logiciel [tels que Boehm, 1981 ; ANSI/IEEE, 1986] est vers l’autre extrême, pour traiter la documentation utilisateur dans le cadre de la configuration logicielle requise et donc à insister exagérément qu’il être largement fini avant même le début de conception de logiciels.
Cet article essaie de mettre la zone peu étudiée de la documentation de l’utilisateur dans le giron de génie logiciel. Je vais décrire une méthode pratique et peu coûteuse qui utilisent certains fournisseurs informatiques commerciaux d’examiner et de surveiller leurs manuels. Gestionnaires de projets de logiciels, les concepteurs et personnel d’Assurance de la qualité pouvez utiliser la méthode pour extraire les éléments formels de la documentation et les tricoter en spécifications, plans de test et annexes.
La scène dans cette méthode ressemblent à des techniques officieuses que beaucoup de gens utilisent lorsqu’ils doivent logiciel documents — à peu près :
  1. Décider quelles sont les caractéristiques de discuter.
  2. Jouer avec des exemples d’applications afin d’apprendre comment le logiciel fonctionne.
  3. Organiser les modèles, procédures, mises en garde et des renseignements dans un ordre raisonnable.
La contribution de cet article est de donner à ces techniques une entreprise mise à la terre en génie logiciel. Cela fait la différence entre une activité de jeu non structuré et une discipline qui prend en charge la définition des objectifs et allocation des ressources (sans rien perdre du plaisir).
Dans la poursuite de fiabilité, ce livre définit exactement est ce qu’un « dispositif » et propose une liste complète des questions qui doivent être remplies afin de documenter chaque fonctionnalité. Je montre aussi comment faire pour déterminer que les demandes examinées sont vraiment utiles, et comment associer les modèles offerts aux lecteurs avec les étapes qu’ils doivent suivre pour utiliser le logiciel. Toutes les étapes de la méthode inclut des règles pour limite l’activité, enregistrer des progrès et examen des résultats.

Avant que je lance dans les fondements théoriques, permettez-moi de décrire certains incidents qui donnent le goût de ce qu’est de travailler avec cette méthode dans un environnement commercial.

  • Lors de l’élaboration d’un système d’exploitation temps réel, les exemples d’un manuel ont été testés sur des systèmes dotés de processeurs jusqu’à quatre et jugés corrects. Cependant, au cours de la prochaine version du produit, l’équipe de test obtenu un système à huit processeurs, relancé les suites de la régression et trouvé une omission subtile dans l’un des exemples. Il a fallu moins d’une heure pour corriger l’exemple tant le texte explicatif dans le manuel.
  • Dans l’effort de documentation pour les outils de traitement parallèle, un exemple assez trivial a retroussé une erreur interne du compilateur dans l’attribution des classes aux variables. L’erreur n’avait jamais été retrouvée par des tests réguliers d’AQ parce qu’une classe a été rarement utilisée, et parce que le testeur a porté sur les stress tests avec irréaliste des constructions de programmation. L’exemple de documentation effectué une opération plus réaliste mélange les données des différentes classes et donc a déclenché l’erreur.
  • Sur un projet en administration de base de données, l’auteur a analysé le matériel pour trouver la première tâche, qu’un administrateur serait susceptible d’effectuer. Elle a découvert que les connaissances requises pour cette tâche (initialiser les informations de sécurité de l’utilisateur) sont actuellement divisé entre les trois manuels distincts. En quelques mois, elle a réalisé un tutoriel qui couvrait cette tâche fondamentale et plusieurs autres en mode simple, procédurale.

 

La documentation utilisateur est l’aboutissement d’un long processus de débat et d’expérimentation tout au long d’un projet de logiciel. Par conséquent, alors que l’impulsion principale de cet article est de favoriser les meilleures publications et la documentation en ligne pour les utilisateurs, certaines de ses recommandations affectera un projet documentation interne et formation du personnel. Ainsi, le livre devrait intéresser les personnes concernées à l’amélioration de l’éducation et la communication parmi le personnel de leur programmation et en particulier avec les moyens de diffuser les idées des concepteurs du projet et des membres supérieurs aux autres membres de l’équipe.
Les trois sections suivantes rôles, objectifs et théorie — Voir la forme générale de la méthode pour la documentation du logiciel. La majeure partie du livre est consacrée à une histoire d’applications pratiques : une description étape par étape dans le procédé et une discussion de détails d’implémentation en mécanique. Je termine avec un résumé de la situation actuelle de la méthode en avantages.

  • Buts
  • Théorie
  • Rôles
  • Méthode
  • Mécanique
  • Avantages
Buts
Les traits de bonne documentation qui peut être développé grâce à une méthode rigoureuse sont :
  • Pour répertorier les composants requis pour chaque fonctionnalité.
  • Pour illustrer chaque caractéristique du produit dans un contexte reconnaissable aux lecteurs.
  • Pour amener le lecteur à petits pas d’utilisations simples d’utilisations complexes.
  • De contre-référence entre des concepts de haut niveau (comme les tâches de l’utilisateur et les modèles de programmation) et des concepts de niveau inférieur (comme Prérequis système et les caractéristiques du produit).
  • Pour refléter les changements du produit par le biais de sa durée de vie.
En revanche, Voici quelques traits qui ne peut pas être vérifiés formellement, mais dépendent de la compétence individuelle et de la subjectivité des producteurs du document — et par conséquent, ne relèvent pas de notre discussion.
  • Pour utiliser des termes qui conviennent pour ses lecteurs.
  • Offrir la bonne quantité d’informations générales.
  • Pour utiliser un format et une mise en page sur la page ou l’écran qu’il est facile à suivre.
  • Rester libre d’erreurs typographiques et d’autres problèmes qui se trouvent dans l’écart entre le matériel que vous pouvez consulter officiellement et le matériel imprimé réel.
Les premiers traits sont essentiellement liés aux caractéristiques du produit et son utilisation, alors que la seconde couvre les aspects psychologiques du document et sa traduction en un moyen de distribution.
Résultats souhaitables ne suffisent pas à définir une méthode de travail utile. La mise en œuvre doit également être possible dans un environnement commercial. Ainsi, une méthode pour produire de la documentation de reliabile devrait se réunir les exigences procédurales suivantes.
  • Utilisation répétable.
Les traits officiellement révisés de la documentation peuvent être vérifiées par le biais de tests de régression à des points réguliers dans le cycle de développement du logiciel.
  • Faible coût.
La méthode ajoute une charge relativement faible pour les responsabilités actuelles, planification et ressources de l’ordinateur d’une équipe de projet commercial.
  • Évolutivité.
Les mêmes techniques essentielles peuvent bénéficier des petits projets (par ex. une personne MIS dirigé vers des utilisateurs internes) ainsi que les plus grands (logiciel commercial pour les utilisateurs finaux, la documentation est le point d’entrée essentiel au produit).
  • Facilité d’intégration et de transfert des connaissances.
Les techniques sonne familiers aux ingénieurs bien formés et personnel d’Assurance de la qualité et s’adaptent à toutes normes qu’ils utilisent d’autres efforts de maintenance de logiciels.
  • Valeur pour une utilisation avec effet rétroactif.
La méthode peut servir à produire de la documentation pour le logiciel qui a déjà été publié et même logiciel dont le concepteur original a quitté ou dont l’équipe de projet a dissous.
Théorie
Autres articles [Oram, 1989 ; Oram, 1991] ont aménagé et justifier la thèse sous-jacente pour une documentation sérieuse :
Les points critiques déterminant la qualité de la documentation du logiciel résident dans la structure du logiciel lui-même, pas dans les choix stylistiques de l’écrivain.
Cet article va montrer qu’on peut produire une description complète de l’utilisation du système de traçage des transformations de données d’une fonction à l’autre. La théorie de soutien pour notre effort est constructive spécification. Il peut sembler un choix surprenant, étant donné que la théorie est surtout connue comme une méthode un peu académique, beaucoup de travail pour construire des preuves formelles [Jones, 1980] et en guise de classes dérivées en programmation orientée objet [Stoy, 1982]. Mais dans cet article, spécification constructive s’avère pour être un moyen simple et puissant pour lier l’utilisation du logiciel avec sa structure logique.
L’idée de base derrière la spécification constructive est de décrire chaque objet de données en ce qui concerne les opérations qui permettra au programme. Par exemple, vous pouvez écrire un cahier des charges d’une pile en décrivant les trois opérations : initialisation, poussant et popping. Aux fins de documentation, nous pouvons définir des fois une direction et une limite à nos efforts par le biais de la règle suivante :

La spécification d’un document de l’utilisateur est terminée lorsqu’il inclut chaque opération valide sur chaque objet de données qui affecte l’état du système, dans un exemple d’application qui provoque un changement d’un état de système utilisateur reconnaissable à l’autre.
Nous devons maintenant déchiffrer les phrases clés « chaque objet de données qui affecte l’état du système » et « état du système utilisateur reconnaissable. » Nous pouvons ensuite joindre la théorie à une vision plus large de modèles mentaux et liens.
Utilisation de produits ayant une incidence sur données
Les données qui se rapportent à la documentation utilisateur tombent dans deux catégories : fonction des arguments et des données statiques (qui comprennent les données stockées dans un support externe). Un des avantages du développement d’applications de l’échantillon, c’est qu’ils aident à révéler la dépendance à l’égard de l’utilisateur des informations d’État. Un document basé sur des exemples ne devrait pas laisser de côté les conditions préalables essentielles ou les besoins de l’environnement, comme pour monter une disquette, afin de réserver les tampons exceptionnellement élevées, ou pour ouvrir une session avec des privilèges spéciaux. Tous ces besoins environnementaux (vaguement liées à la notion des « besoins non fonctionnels » dans [romain, 1985]) sont stockés sous forme de données statiques internes mentionnées précédemment.
Exemples d’Applications
Demandes, conformément à la règle énoncée au début, devraient causes des changements entre les États “utilisateur-reconnaissable”. Cette disposition vise à exclure les exemples factices, comme celui qui simplement convertit un entier en une chaîne de caractères. En revanche, un exemple simple de calcul et génération de rapports qui incluent la conversion entre un entier et une chaîne de caractères peut être un outil d’enseignement précieux, parce que maintenant, la conversion devient partie intégrante d’une tâche plus grande et est justifiée par les exigences de cette tâche. Parce qu’un tel exemple est ancré par des États utiles, reconnaissables à la fois le début et la fin, j’ai inventé la vérification éplacement de terme pour le décrire.
Exemples d’applications peuvent émerger à travers des approches top-down et de bas en haut. L’approche top-down, qui est le plus familier, consiste à recueillir les points de repère et des applications de client que le produit est destiné à soutenir, et les briser en petits morceaux peut être victime d’un examen indépendant. Mais cela ne peut pas assurer une couverture complète de toutes les opérations sur tous les éléments de données. Elle doit donc être accompagnée de l’approche bottom-up, qui est de transformations de données de trace à l’aide de la méthode dans le présent document.
Voici un exemple simple de conception de bas en haut. Les opérations de base sur un identificateur de fichier incluent assignation (par une instruction open), référence (à travers la lecture, d’écriture et déclarations étroites) et activités auxiliaires (tels que FORTRAN INQUIRE ou stat du langage C). Ainsi, on peut créer un exemple simple d’éplacement en ouvrant, par écrit et fermer un fichier. Vérification pourrait consister en comparant le fichier final à une version en boîte, ou de lecture les données dans le programme et vérification de cohérence.
Simple comme tel est un exemple, les enseignements qu’il contient ne sont en aucun cas triviales. Il peut être le modèle pour des applications sophistiquées comme imposant des structures sur des données binaires brutes et d’ouverture d’un tuyau non bloquant les accès (asynchrone). À l’aide de la méthode dans le présent document, on peut construire une description complète du fichier de manutention à travers une série d’exemples de plus en plus complexes.
Cet article est le premier, à ma connaissance, à suggérer une méthode rigoureuse en utilisant des exemples pour assurer une couverture complète du produit. J’ai trouvé qu’un seul autre discussion des exemples de l’utilisateur dans la littérature de génie logiciel [Probert, 1984], mais il les considère une source pour des tests plutôt qu’un outil de formation.
Structure du logiciel et modèles pour utilisation
Une documentation informatique vise à identifier les tâches de l’utilisateur. Mais la caractéristique d’une « tâche », dans le domaine des logiciels, est qu’il est vraiment constitué de nombreuses tâches sur différents niveaux conceptuels.
Par exemple, une base de données relationnelle, utilisateurs peuvent définir leur tâche initialement comme récupérer les entrées qui correspondent à certains critères. Mais pour commencer à utiliser un système d’interrogation typique, ils doivent redéfinir cette tâche comme « une vue de la construction ». Cette tâche dépend à son tour une couche inférieure de tâches comme le choix des clés de recherche, création d’expressions de recherche booléenne et trier les entrées. La documentation décrit dans ce livre aide les utilisateurs à développer des processus de pensée nécessaire pour trouver comment utiliser le logiciel — qui est, pour décomposer leurs tâches jusqu’à ce qu’ils atteignent les atomes représenté par les caractéristiques du produit.
Enseignants et chercheurs en sciences cognitives ont mis l’accent sur le concept des modèles mentaux pour expliquer comment les gens assimilent les informations et l’appliquent dans de nouvelles situations. La recherche plus sophistiquée [par exemple, Brown, 1986 ; Norman, 1986 ; Frese, 1988] renforce la stratégie utilisée dans cet article : que de faire correspondre les modèles de produit utiliser pour la structure logique du logiciel.

Documentation fiable construit des modèles de la structure du produit lui-même, qui offre tant de richesse et de précision. Les modèles sont simplement la couche superficielle des tâches de l’utilisateur, telles que “la recherche” dans l’exemple d’une base de données. L’utilisateur qui consulte la documentation afin d’effectuer une recherche trouve un progressif effondrement dans les niveaux inférieurs des tâches, finissant peut-être dans les arguments d’une clause WHERE en SQL.
Dans la méthode de cet article, les modèles carte directement sur la construction du concepteur du logiciel. Par exemple, un manuel de programmation en temps réel pourrait diviser les applications en cyclique et axée sur l’interruption. Applications cycliques pourraient alors être décomposées davantage dans ceux utilisant plusieurs threads indépendants et ceux qui exécutent plusieurs fonctions à plusieurs reprises dans un thread. Le manuel peut ensuite décrire les environnements dans lesquels chaque modèle serait plus avantageuse et mise en œuvre de chaque modèle par le biais de procédures et exemples.
Liens et Structure d’un Document
À des fins d’apprentissage initial, les utilisateurs ont tendance à lire de façon linéaire (même si ils ont aussi tendance à démarrer au milieu et sautez autour d’un lot). Référence et recherche de pannes, ils préfèrent chercher une structure hiérarchique, tel qu’un index ou un jeu en ligne de liens hypertextes.
Personne n’utilise toutes les fonctionnalités dans un produit. Mais on peut être certain que certains ensembles d’utilisateurs ont besoin des combinaisons particulières de fonctionnalités. Ainsi, j’utilise la métaphore des terrasses pour décrire la structure d’un document informatique. Chaque terrasse comprend un exemple de sa lettre d’explication. Un document peut contenir plusieurs « collines », chacun consistant en un ensemble de terrasses qui deviendra progressivement plus complexe.
Ainsi, un produit de base de données, une colline pourrait offrir des exemples plus compliqués de récupérer les clés, montrant ainsi le lecteur différentes façons de créer une vue de. Une autre colline puisse résoudre les problèmes de stocker physiquement les grandes bases de données. Utilisateurs peuvent grimper les collines dont ils ont besoin pour leurs applications particulières et ignorer les autres collines entièrement. Si de nouvelles fonctionnalités ou nouvelles applications sont ajoutées au cours du développement de produit, l’écrivain peut trouver des endroits pour eux près du sommet de la hiérarchie de la terrasse. Mais la création disciplinée des exemples d’applications s’assure que les utilisateurs peuvent associer des tâches avec les caractéristiques du produit.
Rôles
L’objectif principal de cet article est un bon document pour être remis à l’utilisateur. Mais sa philosophie s’applique à la documentation de projet interne trop. Grosso modo, ce papier demande :
Comment les concepteurs de logiciels acheminent leurs idées pour les membres de l’équipe moins expérimentés au cours de la mise en œuvre du produit et en fin de compte, dans les manuels et les cours de formation, aux utilisateurs finaux du produit ?
Comme toute stratégie de planification, la méthode dans le présent document est moins coûteuse et la plus bénéfique lorsqu’elle est employée depuis les premières phases d’un projet. Les gestionnaires qui lancement le projet peuvent, avec relativement peu d’efforts, préserver certaines applications utilisateur conduire le projet dans la documentation de concepts et d’exigences.
Concepteurs de logiciels ont certainement des modèles d’utilisation à l’esprit comme ils trouver sous-tâches communs, créer des modules et définissent les structures de données de l’ensemble du système. Les modèles doivent figurer explicitement dans les descriptions de conception de logiciels. Si les concepteurs n’ont pas de temps pour créer des exemples complets, ils peuvent déléguer le travail aux autres membres de l’équipe — dans les deux cas, le processus intellectuel de la création d’exemples permet de définir le produit et le décrire à l’équipe.
La méthode dans le présent document est tout aussi précieuse dans le malheureux — mais trop souvent — cas un produit est depuis longtemps sans documentation adéquate dans le domaine, et l’équipe du projet engage un scénariste pour assainir la situation. Maintenant, la méthode fournit des directives pour la reconstruction de la perte d’informations sur l’utilisation. Catégoriser et de traçage des données permet d’établir des informations essentielles, comme quoi de chaque option de la commande pour, et ce qui distingue des commandes similaires. Lorsque les caractéristiques ne peuvent être comprises, et les recherches sur les applications utilisateur supplémentaires sont nécessaires, la méthode permet à l’écrivain identifier les informations manquantes et de poser les bonnes questions.
Méthode
Dans un environnement commercial, la production d’une documentation sérieuse tombe en trois étapes distinctes. Bien que cet article discute les séquentiellement par souci de simplicité, les pressions réelles de développement du projet souvent forcent les variations.
Par exemple, sur un projet avec des délais serrés, certains stades se chevauchent dans un pipeline. Une analyse de données partiellement terminée peut être utilisée pour commencer à développer des exemples, et premiers ensembles d’exemples peuvent être placés dans un ordre provisoire afin que l’écrivain peut commencer à créer le texte.

Changements dans la conception ou la stratégie de marketing compliquent également la méthode en obligeant l’équipe à réitérer les étapes terminées. Si une nouvelle fonctionnalité est ajoutée, chacune des pièces produites dans chaque étape doit être ajusté afin d’inclure la fonctionnalité. Un des points forts de la méthode est que les écrivains peuvent rapidement déterminer l’effet d’ondulation de tout changement sur le point de vue utilisateur entière, et incrémentielles d’apporter des modifications à la documentation si nécessaire.
Étape 1: Répertorier et classer toutes les données éléments influant sur l’utilisateur
Dans la section sur la théorie, j’ai décrit les données d’état système et entrée à quel produit concepteurs doivent être attentifs et montrent comment l’utilisation du produit est entièrement déterminée par ces données. La première étape de la méthode de cet article classe les éléments de données, déterminer le rôle que chacun joue dans le système de logiciel.
Activités
Pour les besoins de documentation de l’utilisateur, quelques catégories simples suffisent pour tenir compte de tous les éléments de données. Ceux-ci apparaissent dans le tableau 1, ainsi que de règles permettant de déterminer la catégorie appropriée pour chaque élément. Catégorisations ne soient pas intuitivement évidentes lorsque l’utilisateur fonctionne à un niveau très éloigné des ingénieurs (comme dans le cas de produits graphiques interactifs) mais malgré cela, les mêmes catégories toujours appliquent. On doit s’habituer à regarder le rôle de l’objet dans l’état du système, plutôt que de regarder les mécanismes superficiels pour sélectionner ou modifier un objet.
Le tableau 1. Éléments de base de données.
Certains gens pourraient vouloir utiliser ces catégorisations comme primitives permettant d’attribuer des catégories plus spécifiques. Par exemple, un identificateur de fichier, un identificateur de processus et un identificateur de canal prennent tous en charge les transformations de données différentes. Ainsi, si votre produit comporte plusieurs éléments de données qui relèvent de ces sous-catégories, vous pourriez trouver il efficace de créer distinct des listes de questions pour chaque sous-catégorie.
De même, certains éléments de données couvrent plus d’une catégorie. Par exemple, un protocole de communication peut définir plusieurs encodages possibles pour un élément de données unique, les paramètres de certains bits déterminent quel codage s’applique. Applications nombreux UNIX et X Window System utilisent des syndicats de langage C à des fins similaires. Ces complexités signifient simplement que vous devez poser les questions appropriées pour chaque utilisation possible de l’élément de données.
Puisque l’accent est mis sur l’objet de données, il est inutile de se préoccuper de son type, la portée ou la plage. (Ces considérations apparaissent bien sûr par la suite dans la documentation, pour décrire les restrictions et les conditions d’erreur.) Ni les types de données dérivés ou niveaux d’indirection important ; Nous ne craignons qu’avec les types de transformations autorisées.
Une fois trouvée une catégorie pour chaque élément de données, nous savons que la documentation doit fournir pour cet élément. La liste des questions pour chaque catégorie figure ci-dessous.
  • Drapeau
  1. Paramètre par défaut.
  2. Qui définit, pourquoi et comment.
  3. Qui réinitialise (efface), pourquoi et comment.
  4. Qui lit, pourquoi et comment.
  • Compteur
  1. Qui initialise, pourquoi et comment.
  2. Qui incrémente ou décrémente, pourquoi et comment.
  3. Qui lit, pourquoi et comment.
  • Identificateur
  1. Quel objet qu’il veut dire.
  2. Qui initialise il et comment.
  3. Qui y fait référence, et quelles opérations sont généralement effectuées sur l’objet.
  4. Si jamais, il sera supprimé et comment.
  • Table
  1. Ce qui concerne chaque entrée dans la table et comment sélectionner il (au moins un exemple par correspondance dans la table).
  • Données d’application
  1. Ce que la valeur par défaut est et pourquoi l’utiliser.
  2. Comment une valeur est utilisée.
  3. Considérations particulières. Elles apparaissent plus souvent sur les bords de la plage. Par exemple, zéro ou null a souvent une signification particulière qui ne peut être appliquée de manière intuitive dans la gamme normale des valeurs.
Résultat
Étape 1 a atteint deux mesures importantes qui sont nécessaires pour gérer toute activité. Tout d’abord, en décomposant un effort de documentation qui jusqu’à présent a été indifférencié, cette étape permet à l’équipe prioriser les tâches subordonnées et les assigner aux membres de l’équipe différente. Deuxièmement, en fournissant une liste complète des tâches subordonnées, il fournit un guide brut certes, mais toujours utile pour faire des progrès de la documentation du mesurable.
Le résultat concret de l’étape 1 est une liste comme tableau 2. Ce tableau est extrait d’un document interne réel développé lors de la conception d’un produit de programmation pour les graphiques de la fenêtre. La colonne de gauche est simplement une liste de fonctions, tandis que la colonne suivante affiche la liste d’arguments de la fonction. Si le produit inclut des données de l’État, ceux-ci peuvent être répertoriés dans la colonne de gauche aussi bien.
Le tableau 2. Catégorisation de données, document de travail pour le suivi des fonctions
Call Argument/ Data item Categorization Expected range Examples
Init() return value table True (success)
False (failure), BadAccess
display
identifier retrieved from server
ChangeScheduler()
display
identifier retrieved from server
client
identifier from ThisClient()
when
table Immediate
Sequential
params:
   type
table RoundRobin
PriorityBased
   slicevalue
counter > 0
   slicetype
table TimeBased
RequestBased
   decaylevel
counter MinPriority to MaxPriority
   decayfreq
counter > 0
   decayunits
table TimeBased
RequestBased
   priority
counter MinPriority to MaxPriority
   priomode
table Absolute
Relative
.
.
.

L’argument d’un appel est une structure complexe contenant plusieurs éléments de données distinctes. Le tableau 2 reprend cette disposition par la mise en retrait les éléments de données sous le nom de la structure, params.
Certains éléments de données nécessitent maintenant plus d’une ligne, car plusieurs paramètres doivent être documentées. En particulier :
  • Drapeaux nécessite deux rangées.
  • Les compteurs et les données d’application exigent parfois des lignes supplémentaires pour les valeurs avec des significations particulières (telles que les valeurs négatives ou zéro).
  • Tables nécessitent une ligne pour chaque valeur juridique.
La colonne de catégorisation reflète les critères du tableau 1. La colonne de gamme attendue ressemble aux domaine et informations recueillies dans la norme pratiques d’Assurance de la qualité. En général, les troisième et quatrième colonnes incarnent la stratégie pour découvrir le produit et répondre aux questions décrites précédemment.
La colonne de droite est actuellement vide, mais est remplie pendant l’étape 2 avec une liste d’exemples qui illustrent chaque élément de données spécifique à chaque valeur spécifiée.
Un autre exemple de sortie phase 1 pour le logiciel plus familier, le tableau 3 montre la catégorisation de données pour l’appel de signal sur les systèmes UNIX (comme normalisés en ANSI C).
Tableau 3. Catégorisation des données pour UNIX signal appel.
Call Argument/ Data item Categorization Expected range Examples
signal signo identifier mnemonic for signal
sa_handler table entry SIG_DFL
SIG_IGN
function
return value table entry SIG_DFL
SIG_IGN
function
SIG_ERR
Examen
Cette étape produit une petite quantité de la production, étroitement liée à la conception de logiciels. Évaluateurs devraient examiner la sortie pour s’assurer que :
  1. Tous les arguments de la fonction et les données statiques sont répertoriées, tant que ceux-ci pourraient avoir un effet sur l’utilisation du produit.
  2. Chaque élément de données est correctement classé.
Analogies dans le génie logiciel
En termes de génie logiciel, l’objectif de cette étape peut être comparé aux critères d’acceptation.
Analogies en rédaction technique
Dans les termes utilisés par la littérature de rédaction technique, ce stade a atteint l’objectif d’exhaustivité.
Étape 2: Développer des exemples
À l’étape 1, la méthode puisé profondément dans la logique interne du produit. Le résultat fut un historique des modifications apportées à chaque élément de données. Il est temps maintenant de revenir vers le haut au point de vue de l’utilisateur.
Étape 2 s’appuie les modifications pour chaque élément de données dans des applications de faible mais réalistes. Cette étape contient l’alchimie qui transforme les États du système des tâches de l’utilisateur et les modèles de programmation.
Activités
Dans une certaine mesure, les exemples émergent naturellement des réponses aux questions énumérées plus haut. Par exemple, en demandant « quelle est la fonction assigne l’identificateur qui apparaît comme cet argument? », on Découvre les sortes d’initialisation requise dans un exemple d’application. Tout en suivant les lignes de transformation de données, on découvre des fonctions qui vont ensemble naturellement. Finalement, un ou deux exemples extrêmement bas apparaissent comme les plus simples applications possibles qui utilisent le produit de faire quelque chose de constructif.
La réalisation de la phase 2 est de relier les caractéristiques du produit à couches progressivement plus élevés des tâches. Les liens forment collectivement un système de renvoi que l’écrivain peut se transformer en un index pour un manuel ou un ensemble de liens dans la documentation en ligne.
Exemple-bâtiment est une activité limitée, car les étapes précédentes ont déjà défini quelles données doivent figurer les éléments, et quelles questions la documentation doit répondre pour chacun d’eux. Le succès de l’effort de documentation est désormais quantifiable. Si le temps ne permet pas l’exploration complète de chaque élément de données, l’équipe d’ingénierie peut choisir de se concentrer sur les points critiques et d’ignorer ceux obscure.
Résultat
La langue ou le support pour obtenir des exemples dépend du type de produit étant documenté. Fonctions et langages de programmation sont illustrées par des exemples de code. Systèmes d’exploitation et des services publics interactifs peuvent être illustrées par la série des invites et des commandes. Les applications de point-and-click appellent pour des photos ou des descriptions des mouvements de la souris et le clavier.
Dans la fenêtre projet discuté plus tôt, la recherche d’exemples radicalement modifiée mise au point du document. Aucune application significatif ne pourrait être développée qui sont restés dans le champ d’application du produit. Au lieu de cela, l’équipe a décidé de tirer dans les nombreuses tâches que laïcs en dehors du logiciel qu’ils construisaient, mais qui étaient une partie inséparable de la base pour le logiciel de l’application :
  • Contrôle sur l’environnement de fenêtrage total, qui pourrait contenir un nombre quelconque d’applications indépendantes.
  • Communication et synchronisation en utilisant les canaux fournis par le système d’exploitation.
  • Réponses à l’entrée en temps réel, des formes périodiques et urgents.
Le document initial créé pour examen pendant l’étape 2 ressemblait le pseudo-code illustré au tableau 4. Le document final est un ensemble de programmes réels.
Tableau 4. Exemple de base de l’évolution de la planification politique, lorsque l’utilisateur appuie sur le bouton.
External event Program action
Init(display)
        .
        .
        .
client_id[0] = ThisClient(display)
params.type = PriorityBased
params_raise.type = PriorityBased
params.u.p.slicevalue = long_draw + 10
params_raise.u.p.slicevalue = long_draw + 10
        .
        .
        .
ChangeScheduler(display, client_id[0], &params, Sequential)
Button press
for (i=0; i<num_clients; i++)
    ChangeScheduler(display, client_id[i], &params_raise, Immediate)
        .
        .
        .
Un sous-ensemble du tableau 4 est représenté par le code C ci-dessous, qui est un extrait d’un programme réel, tester les fonctionnalités du produit. Comme pour le test de logiciel, un jeu complet d’exemples utilisateur devrait inclure certains qui sont censés ne pas, par délibérément provoquant des erreurs ou enfreint les règles documentées.

#include “plot_xlib.h”
#include “root_defs.h”

void Xserver_priority_initialize(top)
DISPLAY_INFO *top;
{
rtxParms set_rtxp;

/* initialize with privileges to change global parameters */
(void) PrivilegeInit(top->display);

/* client-specific parameters will affect just this client —
actually, this fragment affects only global parameters */
top->client = ThisClient(top->display);

/* this will tell library to check the set_rtxp.u.p parameters */
set_rtxp.type = PriorityBased;

/* mask makes scheduler change slice and decay, but leave priority alone */
set_rtxp.mask = Slice | DecayLevel | DecayAmount | DecayFrequency;

/* set the parameters of the rtxParms structure */
set_rtxp.u.p.slicevalue = NEW_SLICE;
set_rtxp.u.p.dlevel = CEILING_FOR_DECAY;
set_rtxp.u.p.damount = 1;
set_rtxp.u.p.decayfreq = DECAY_TIME;
set_rtxp.u.p.slicetype = TimeBased;
set_rtxp.u.p.decayunits = TimeBased;

/* Everything before was prepartion — this call makes the change */
ChangeScheduler(top->display, top->client, &set_rtxp, Sequential);
}


>

Examen
Puisque cette étape produit une grande partie de la production, elle est souvent réalisée progressivement. Les principaux critères sont :
  • Utilisation correcte de chaque fonction ou une commande.
  • Respect des conditions préalables, avec la mise en place correcte et les activités de nettoyage.
  • Couverture complète des modèles utilisation définie par les membres du projet principal et chefs de projet.
  • Délimitation correcte des tâches sous chaque modèle d’utilisation.
Certains critères optionnels supplémentaires peuvent aider à améliorer la qualité de la documentation finale ou l’effort d’entretien pour obtenir des exemples. Ces critères exigent le jugement intuitif et un sens de l’environnement de l’utilisateur.
  • Respect des pratiques standards, recommandés en dehors des caractéristiques du produit.
  • Optimalité. Chaque exemple doit être plus petit et le plus simple qui pourrait illustrer l’utilisation des données, tout en conservant certains naturalisme.
  • Utilité. Toutes autres choses étant égales par ailleurs, il serait utile de construire des ensembles d’exemples qui approche réaliste des applications. Cependant, utilisateurs et applications évoluent de manière imprévisible, il est donc beaucoup plus important pour obtenir des exemples être simple et faire comprendre l’utilisation de base du produit.
  • Indépendance de la machine. Test de régression est compromise si l’exemple suppose implicitement une certaine architecture sous-jacente, structure de répertoire ou d’autres éléments externes qui sont connues pour changer au fil du temps.
  • Facilité d’essai. Par exemple, un exemple qui génère les données en interne ou utilise l’entrée prédéfinie nécessite beaucoup moins de travail durant la régression stable que celle qui interagit avec un utilisateur pour son entrée.
Analogies dans le génie logiciel
L’objectif de cette étape peut être comparé à développer des suites de tests. En fait, les exemples devraient être intégrées dans les tests de régression, tel que discuté dans la section mécanique du présent document. Au cours de la conception de produits, exemples valident l’effort de documentation en veillant à ce qu’il prend en charge les applications utilisateur nécessaires et les styles. Les tests de régression, à son tour, vérifient que les exemples reflètent le fonctionnement du produit sur toute la durée du produit.
Analogies en rédaction technique
En termes de rédaction technique, la décomposition des tâches utilisateur remplit les objectifs d’orientation de convivialité et de la tâche.
Étape 3: Commander les exemples
Ce stade organise les exemples de l’étape 2 dans une structure qui détermine l’ordre de présentation dans le document final. La structure possède des fois une simple commande linéaire et une hiérarchie arborescente. Les éléments linéaires sera plus évidentes dans un manuel imprimé et les éléments hiérarchiques dans la documentation en ligne.
Activités
Étape 3 continue le mouvement commencé dans l’étape 2, loin de la structure du logiciel et plus vers l’utilisateur humain. Les objectifs sont de rendre aussi facile que possible commencer avec un produit, puis d’identifier et d’intégrer des améliorations utiles. Exemples fournissent des critères naturels pour commander de façon linéaire :
  • Applications simples avant complexes. Commencez par l’exemple le plus simple possible d’utilisation du produit et essayer d’introduire une ou deux nouvelles fonctionnalités dans chacun des exemples successifs.
  • Caractéristiques communes avant ceux obscure. Des options spéciales qui répondent à des besoins rares peuvent être isolées près de l’arrière du document.
Les aspects hiérarchiques de l’organisation proviennent des modèles et des tâches examinées au titre de l’étape 2. Ces aide pour regrouper les exemples que les utilisateurs ont besoin à un moment donné.
Résultat
Le résultat de l’étape 3 est un ensemble réordonnée des exemples organisés selon une hiérarchie des tâches. Puisqu’il représente la structure finale du manuel, réviseurs peuvent examiner la hiérarchie afin de décider si les caractéristiques sont présentées dans un ordre approprié et compte tenus de la bonne quantité d’attention.
À la fin de cette étape, l’équipe d’ingénieurs a formellement définis tant les thèmes et la structure de la documentation du produit. La richesse et le pouvoir des informations que cette ressource offre aux rédacteurs techniques ne peuvent être égalées par toute autre méthode. Écrivains peuvent maintenant préparer des renseignements généraux et des textes narratifs qui explique les modèles, les tâches et les techniques. Le système de références croisée permet de construire l’index.
Comme un bref exemple de structure de document conçu par le biais de l’analyse des données, voici l’esquisse pour une description en ligne, entièrement axée sur la tâche de signaux ANSI C et POSIX [ANSI, 1989 ; IEEE, 1988].
  • Piégeage
    • Appel de base de signal
    • Signaux POSIX (sigaction)
      • Définition
      • Drapeaux
      • Erreurs
    • Fourches (héritant des actions de signal)
  • Gestionnaires
  • Envoi
    • appel de tuer
      • Exemple de base
      • Processus/groupes
      • Privilège
      • Erreurs
    • Communication interprocessus
    • faire appel
    • appel d’alarme
  • Blocage
    • Signal réglé (manipuler le type de données sigset_t)
    • Protection des données (appel sigprocmask)
    • Protection de gestionnaire (en appel sigaction)
    • Signaux en attente (sigpending call, appel de sigismember)
  • En attendant le signal (appel sigsuspend)
Le document se déplace de questions simples aux plus complexes, librement rompre la discussion d’un seul appel orientée vers le travail l’exige. Par exemple, la section sur « Envoi » met l’accent sur la communication avec un seul processus (le cas le plus courant), mais offre également une brève discussion sur la question plus complexe des groupes de processus. Bien que le blocage est une question cruciale, il vient tard dans le document car elle nécessite une bonne compréhension des questions antérieures. Nombreux problèmes non directement liés aux appels apparaissent également dans le document, comme la nécessité de passer des informations entre le gestionnaire et le programme principal à l’aide de données volatiles, atomiques.
Examen
L’examen de la phase 2, si effectué minutieusement, a résolu les questions les plus importantes de documentation. Examinateurs doivent être en mesure d’accepter, à l’étape 3, que les modèles, des tâches et des exemples sont les meilleurs disponibles. Ainsi, l’examen à l’étape 3 vérifie si :
  • L’organisation linéaire est meilleurs disponible, en ce qui concerne d’abord les applications plus simples et plus fréquents.
  • L’organisation hiérarchique relie toutes les couches de modèles, les tâches et fonctions créées à l’étape 2.
Après cette étape, lorsque les matériaux sont entre les mains des écrivains — le focus se déplace à la révision du texte en ce qui concerne les exemples. Examen des documents devient beaucoup plus facile et plus gratifiant, parce qu’il peut se concentrer sur de petites surfaces du document et poser des questions dont les réponses sont assez faciles à déterminer : par exemple, si les procédures écrites résument fidèlement les exemples, et si le texte avertit les utilisateurs au sujet des sources potentielles d’erreurs.
Analogies dans le génie logiciel
Cette étape n’a pas une contrepartie réelle en génie logiciel, parce que les programmes ne sont généralement pas des textes linéaires.
Analogies en rédaction technique
En termes de rédaction technique, ce stade remplit les objectifs de conception de documentation structurée, de filtrage et le rythme des informations faciles d’apprentissage et de recherche.
Mécanique
Cette section montre quelques-unes, les outils et les structures organisationnelles que mes collègues et moi avons utilisé pour intégrer des exemples de tests de régression. Cette partie de l’effort de révision a offert le plus de récompenses en ce qui concerne le temps investi et des ressources.
Un exemple simple est fourni par un livre sur l’utilitaire make du système UNIX. L’analyse de données inclus toutes les options de la commande, en particulier une option – n qui provoque l’utilité d’imprimer une série de commandes.
Un test intéressant pour l’option-n est un ensemble d’imbriqué ou récursive faire des commandes. Tout d’abord, créez un fichier nommé makefile avec les spécifications pour le faire. Ce qui suit est simplifié mais toujours réaliste exemple.

all :
${MAKE} enter testex

enter : parse.o find_token.o global.o
${CC} -o [email protected] parse.o find_token.o global.o

testex : parse.o find_token.o global.o interact.o
${CC} -o [email protected] parse.o find_token.o global.o interact.o


Interactivement, on peut tester l’option-n en entrant la commande :
make -n all
qui doit produire la sortie comme :

make enter testex
cc -O -c parse.c
cc -O -c find_token.c
cc -O -c global.c
cc -o enter parse.o find_token.o global.o
cc -O -c interact.c
cc -o testex parse.o find_token.o global.o interact.o


Tandis que quelques lignes de sortie varient d’un système, d’autres sont raisonnablement prévisibles. Ainsi, on pourrait commencer à automatiser le test de rediriger la sortie vers un fichier et ensuite vérifier si une des lignes est correcte :

make -n all > /tmp/make_n_option$$
grep ‘cc -o enter parse.o find_token.o global.o’ /tmp/make_n_option$$


Enfin, nous pouvons mettre la séquence entière dans un test de régression en la faisant fonctionner comme un script shell. Le résultat final est reproduit ci-après. Pour les lecteurs qui ne sont pas familiers avec les scripts shell, je dirai simplement que celui ci-dessous est alimenté par un état de sortie invisible retourné par chaque commande.

rm -f *.o enter testex
if
make -n all > /tmp/make_n_option$$
then
if
grep ‘cc -o enter parse.o find_token.o global.o’ /tmp/make_n_option$$
then
exitstat=0
else
echo ‘make -n did not correctly echo commands from recursive make’
exitstat=1
fi
else
echo ‘make -n exited with error: check accuracy of this test’
exitstat=2
fi
rm -f /tmp/make_n_option$$
exit $exitstat


Souligner de cet exemple est qu’elle révèle des incompatibilités entre les systèmes UNIX. Alors que le test utilise des fonctionnalités tout à fait standards, documentées, certaines variantes de la marque n’ont pas eux appliquées.
Ci-dessous vous pouvez voir un autre modèle d’automation de test, à travers un court exemple d’une section d’un manuel de FORTRAN sur le traitement en parallèle. Le manuel comprend marginales commentaires expliquant la procédure, qui remplir un tableau en parallèle dans une boucle.

REAL A, B, ARRAY(100), TMPA, TMPB
C
PRINT*, ‘Input two reals:’
READ (*,*) A, B

CPAR$ PARALLEL PDO       NEW(TMPA, TMPB)
CPAR$ INITIAL SECTION
TMPA = A
TMPB = B
CPAR$ END INITIAL SECTION
DO 20 I = 1, 100
ARRAY(I) = ARRAY(I)/(SIN(TMPA)*TMPB + COS(TMPB)*TMPA)
20      CONTINUE


Le code suivant montre l’exemple augmentée par le personnel d’Assurance de la qualité d’être d’autovérification. L’exemple n’inclut pas les observations d’en-têtes longs contenues dans l’essai proprement dit, pour décrire l’objectif de l’exemple et inclure un script simple pour la course et vérifier. Le tableau ARRAYVFY a été ajouté pour stocker des données de comparaison et la variable EXITSTAT pour indiquer si des erreurs ont été détectées. Une section de la vérification à la fin du programme simplement effectue la même opération dans l’ordre qui l’exemple exécutée en parallèle et les résultats des contrôles. Ainsi, cet exemple de programmation est totalement autonome. Cependant, la technique plus familier de la comparaison d’une sortie contre un fichier pré-existant de bonnes réponses est tout aussi bonne et a été utilisée par l’Assurance de la qualité pour quelques autres exemples dans la même suite de tests.

REAL A, B, ARRAY(100), TMPA, TMPB
REAL ARRAYVFY(100)
INTEGER EXITSTAT /0/

DO 10 I = 1, 100
ARRAY(I) = I
ARRAYVFY(I) = I
10   CONTINUE

PRINT*, ‘Input two reals:’
READ (*,*) A, B

CPAR$ PARALLEL PDO       NEW(TMPA, TMPB)
CPAR$ INITIAL SECTION
TMPA = A
TMPB = B
CPAR$ END INITIAL SECTION
DO 20 I = 1, 100
ARRAY(I) = ARRAY(I)/(SIN(TMPA)*TMPB + COS(TMPB)*TMPA)
20      CONTINUE
C
C ——  VERIFY  ———————————————–
C
DO 100 I = 1, 100
ARRAYVFY(I) = ARRAYVFY(I)/(SIN(A)*B + COS(B)*A)
100    CONTINUE
DO 200 I = 1, 100
IF (ARRAY(I) .NE. ARRAYVFY(I)) THEN
PRINT *, ‘ Error in array on element I’,I,
&                ARRAY(I), ‘ <> ‘, ARRAYVFY(I)
EXITSTAT = 1
ENDIF
200    CONTINUE
CALL EXIT (1)
END


Pour intégrer le test dans nos suites de régression, un membre du personnel tout simplement ajouté le code source et les procédures de test existantes permettant de compiler, exécuter le programme et vérifier l’état de sortie. J’ai délibérément montré le primitivisme de nos procédures — en s’appuyant simplement sur les scripts shell et d’autres outils de système UNIX standards — pour montrer combien peu les frais généraux de développement de test peuvent être. Pendant les quelques premiers tests pour chaque projet a pris un certain temps (environ une heure-personne par exemple documentation) de créer nous bientôt se familiariser avec la procédure et obtenu au point nous pourrions faire un exemple à environ 10 minutes, un test de vérification automatique.
Naturellement, essai développement serait facile avec des outils plus avancés. Certains des domaines de recherche comprennent :
  • Pliage de l’analyse de la documentation avec la création de la spécification fonctionnelle et le plan de test, afin d’éliminer le dédoublement des efforts. Actuellement, la méthode décrite dans le présent document est porte sur complètement séparer des autres les efforts et tous les programmes créés par ces efforts nécessitent beaucoup d’adaptation avant d’être adapté pour des exemples de la documentation.
  • Maintien d’une seule source de chaque exemple pour le test de régression et le document. Cela nécessiterait un outil qui extrait et met en forme les parties de l’exemple en fait nécessaire dans le document. Le processus est en proie à des difficultés et peut-être pas en vaut la chandelle. Presque n’importe quel changement à un exemple requiert un changement correspondant au texte explicatif dans le document — c’est la raison pour la méthode dans le présent document. Par conséquent, il pourrait être préférable de garder les écrivains impliqués et forcer les changements à transférer manuellement le document.
  • Automatisation de la transformation d’utilisateur exemple (ci-dessus) au test de régression complète (également indiqué ci-dessus). Comme la plupart d’automatisation des tâches de génie logiciel, c’est un domaine délicat.
  • Crochets en développement dans les systèmes afin de permettre d’autres automation. Dans la programmation en temps réel, par exemple, il est très difficile de déterminer si élever sa priorité résultats vraiment à obtenir plus de temps CPU. De même, il est difficile de tester un produit graphique sans manuellement à l’aide de la souris et observer personnellement la sortie. Ce sont des problèmes bien connus dans l’industrie informatique et dépassent largement le domaine de la documentation de l’utilisateur.
  • Élaboration de règles qui aident l’équipe à prévoir des zones de rupture. Il s’agit d’un autre dilemme classique de génie logiciel. Par exemple, on ne peut dire si un exemple abouti à un fichier endommagé à moins que le test de régression vérifie ce fichier.
  • Formaliser l’affectation des responsabilités. Combien développement exemple devrait être fait par les concepteurs de logiciels, de programmeurs et d’écrivains ? À quel moment ces gens peuvent retourner un exemple brut pour Assurance de la qualité et dire « Maintenant automatiser » ?
Avantages
La méthode présentée dans cet article a évolué à travers de nombreux projets mes collègues et j’ai appliquent les techniques de génie logiciel documentation utilisateur :
  • Fonctions et techniques de contrôle graphique de la fenêtre (dont les extraits ont été utilisés dans la section de la méthode).
  • Techniques de programmation avec des signaux.
  • Configuration et test de OSI et les réseaux locaux.
  • Configuration, contrôle d’accès et les techniques de requêtes pour bases de données.
  • Bibliothèques C et instructions du langage FORTRAN qui activent le traitement en parallèle.
  • Contrôle programmation en temps réel sur le cadencement, programmation, allocation de processeur et manipulation de fichiers.
  • Langue débogueurs et renforcement des programmes utilitaires.
Le projet sur les signaux était un document en ligne, tandis que le reste étaient des manuels papier. Plupart des projets impliqués complexe programmation Outils, qui peuvent biaiser la méthode. Mais les petites expériences produisant la documentation de l’utilisateur final, ainsi que les considérations discutées dans la section théorie de ce papier, suggèrent que la méthode peut être réussie pour tous les publics et tout produit de l’ordinateur.
une documentation sérieuse a remplacé un ancien manuel pour le même produit, des comparaisons sont révélatrices. Les nouveaux documents ont été généralement acceptés pour afficher les avantages suivants :
  • Ils ont beaucoup plus d’informations, tout en étant plus courte que leurs prédécesseurs.
  • Ils dépensent une bien plus grande quantité d’espace sur les exemples (souvent 50 %), mais l’information narrative clairsemée sort plus compréhensible et pertinente.
  • Ils trouvent des milieux naturels et des applications utiles pour fonctions complexes de documents antérieurs décrits de manière confuse et difficile que beaucoup de lecteurs ne puisse pas de sens d’eux du tout.

La méthode générale pour la production d’une documentation sérieuse a maintenant atteint un état relativement stable, et est assez bien défini pour être transférables. Comme l’utilisation des méthode tartinades, je souhaite créer une communauté qui peut développer des outils de plus en plus sophistiquées pour implémenter les étapes de développement et plus des données de recherche par lequel la méthode peut être évaluée. Pendant ce temps, nos succès pratiques date, ainsi que l’avancée théorique claire qui cette méthode représente sur les autres méthodes de documentation, il devraient être attrayante pour les équipes de développement logiciel.
Références
ANSI, 1989.
ANSI, American National Standard for Information Systems—Programming Language—C, X3.159-1989, ANSI, New York, NY, 1989.
ANSI/IEEE, 1986.
ANSI/IEEE, IEEE Standard for Software Verification and Validation Plans, IEEE Std. 1012-1986, IEEE, New York, NY, 1986.
Boehm, 1981.
Boehm, Barry W., Software Engineering Economics, Prentice-Hall, Englewood Cliffs, NJ, 1981.
Brown, 1986.
Brown, John Seely, “From Cognitive to Social Ergonomics and Beyond,” in User Centered System Design: New Perspectives on Human-Computer Interaction, ed. Donald A. Norman and Stephen W. Draper, Lawrence Erlbaum Associates, Hillsdale, N.J., 1986, pp. 453-486.
Frese, 1988.
Frese, Michael, et al., “The effects of an active development of the mental model in the training process: experimental results in a word processing system,`” Behavior and Information Technology, vol. 7, no. 3, 1988, pp. 295-304.
IEEE, 1988.
IEEE, Portable Operating System Interface for Computer Environments, IEEE Std. 1003.1-1988, IEEE, New York, NY, 1988.
Jones, 1980.
Jones, Cliff B., Software Development: A Rigorous Approach, Prentice-Hall International, London, England, 1980.
Norman, 1986.
Norman, Donald A., “Cognitive Engineering,” in User Centered System Design: New Perspectives on Human-Computer Interaction, op.cit., pp. 31-61.
Oram, 1989.
Oram, Andrew, and Kathleen A. Ferraro, “Sentence First, Verdict Afterward: Finding the Prerequisites for Good Computer Documentation,” Proceedings of the ACM SIGDOC ’89 Conference, ACM, New York, 1989.
Oram, 1991.
Oram, Andrew, “The Hidden Effects of Computer Engineering on User Documentation,” in Perspectives on Software Documentation: Inquiries and Innovations, ed. Thomas T. Barker, Baywood Press, Amityville, NY, 1991.
Probert, 1984.
Probert, Robert L., and Hasan Ural, “High-Level Testing and Example-Directed Development of Software Specifications,” Journal of Systems and Software, vol. 4, pp. 317-325, 1984.
Roman, 1985.
Roman, Gruia-Catalin, “A Taxonomy of Current Issues in Requirements Engineering,” IEEE Computer, vol. 18, no. 4, April 1985, pp. 14-21.
Stoy, 1982.
Stoy, J., “Data Types for State of the Art Program Development,” in State of the Art Report: Programming Technology (Series 10, no. 2), ed. P. J. L. Wallis., Pergamon Infotech Ltd., Maidenhead, Berkshire, England, 1982, pp. 303-320.
Remerciements
Parmi les écrivains et le personnel d’Assurance de la qualité qui ont travaillé sur une documentation sérieuse avec moi, je tiens particulièrement à remercier Sara Alfaro-Franco, Kathie Mulkerin, John Morrison, Sharon DeVoie et Jean Sommer pour l’utilisation et l’évaluation de la méthode. Je remercie également MASSCOMP, Concurrent Computer Corporation et de produits informatiques Hitachi support des expériences et l’effort de recherche vers une documentation sérieuse.