ANSI INCITS TR 8-1988 Information Processing Systems Technical Report User Documentation for Consumer Software Packages.pdf

1、ANSI INCITS TR-8-1988(formerly ANSI X3/TR-8-1988)Information Processing SystemsTechnical ReportUser Documentation forConsumer Software PackagesPublished by American National Standards Institute 11 West 42nd Street, New York, New York 10036 Copyright 0 1990 by American National Standards institute Al

2、l rights reserved. No part of this publication may be reproduced in any form, in an electronic retrieval system or otherwise, without prior written permission of the publisher. Printed in the United States of America Information Processing Technical Report Systems X3/TR-8-88 User Documentation for C

3、onsumer Software Packages Developed by American National Standards Committee X3, Information Processing Systems X3s Technical Report Series This Technical Report is one in a series produced by the American National Standards Committee, X3, Information Processing Systems. The Secretariat for X3 is he

4、ld by the Computer and Business Equipment Manufacturers Association (CBEMA), 311 First St. NW, Suite 500, Washington, DC 20001-2178. As a by-product of the standards development process and the resources of knowledge devoted to it, X3 from time to time produces Technical Reports. Such Technical Repo

5、rts are not standards, nor are they intended to be used as such. X3 Technical Reports are produced in some cases to disseminate the technical and logical concepts reflected in standards already published or under development. In other cases, they derive from studies in areas where it is found premat

6、ure to develop a standard due to a still changing technology, or inappropriate to develop a rigorous standard due to the existance of a number of viable options, the choice of which depends on the users particular requirements. These Technical Reports, thus, provide guidelines, the use of which can

7、result in greater consistency and coherence of information processing systems. When the draft Technical Report is completed, the Technical Committee approval process is the same as for a draft standard. Processing by X3 is also similar to that for a draft standard. ii TABLE OF CONTENTS PAGE PART 0 -

8、 OVERVIEW Section 01. Introduction . 1 1. Preface 1 2.Abstract . 1 3.Scope . 1 4. Application 2 5.Structure 2 6. Committee . 2 Section 02. Definitions. . 3 Section 03. Key Words . 5 PART 1 - USER DOCUMENTATION Section 01. General Information 7 1. Scope . 7 2. Application 7 3. Structure 7 4. Suppleme

9、nts . 7 Section 02. Components of User Documentation 8 :l. Introduction . 8 2. Reference Documentation . 8 3. Training Documentation . 11 4. Quick-Reference Documentation 11 Section 03. Preparing a Table of Contents . 12 1. Introduction 12 2. Format . 12 3. Content 12 4. Examples 13 Section 04. Prep

10、aring a Table of Illustrations 14 1. Introduction 14 2.Format.l 4 3. Content 14 4. Examples 14 Section 05. Preparing an Installation Guide . 15 1. Introduction 15 2. Environment 15 3. Preh-ninary Instructions . 15 4. Installation . 16 5. Modifying Software 16 6. Verification . 16 7. Conversion of Ex

11、isting Files 17 8.Uninstal.l . 17 Section 06. Preparing a Users Guide . 18 1. Introduction 18 2. Format . 18 3. Content 18 4. Additional Features . 19 5. Example of a Functional Section . . 20 . . . m Section 07. Preparing a Command Guide . 21 1. Introduction 21 2.Format.2 1 3.Content 21 4. Examples

12、 22 Section 08. Preparing a Technical Reference . 23 l.Introduction 2. Format . “2 . 3. Content 23 Section 09. System Messages 25 l.Introduction 2 5 Z. to meet this need most easily, incorporate a copy of the cover sheet into the users manual (either include a second copy within the manual or format

13、 the cover document approp- riately and instruct the purchaser where to file it). This report is not intended to dictate arrangement, style, sequence, format, or language. Material of this type, where shown, represents recommendations and suggestions only. Examples are generic, intended to illustrat

14、e the subject discussed. 5. strnctnre In general, the structure of this report matches that of the international standard. Part 0 provides an over- view of the Technical Report itself. Part 1 provides a detailed description of user documentation. Part 2 provides a detailed description of purchaser d

15、ocumentation (Cover Information). Parts 1 and 2 are divided into sections that detail the many components of documentation. The various sections are divided into appropriate subsections (paragraphs). Throughout the Technical Report, the following conventions identify the importance to the audience:

16、ESS - Essential, information must be supplied CON - Conditional, information must be supplied when relevant OPT- Optional, information may be supplied at the discretion of the manufacturer or marketing organization 6. Committee This document was prepared by Technical Committee X3K1, Computer Documen

17、tation. Major participants in the development of this manual included: G. L. Calleso John C. Hackney (Chair) Phyllis S. Illyefalvi (Editor) Vincent F. Iuliano Marshall Lee Caroline Levinson Muriel McGhee Albrecht Neumann (deceased) Susan Schluederberg Jo-Anne Tanenbaum Richard Werling Elaine M. Wing

18、er Valerie B. Winkler 2 SECTION 02 - DEFINITIONS ASCII (American National Standard Code for Information Interchange ). A symbolic interpretation into control and graphic characters of a unit of computer data made up of 8 bits. (Also see EBCDIC.) ASCII and EBCDIC function similarly but interpret the

19、bit values differently; for example: 0100 0001 is the binary or 8bit value that ASCII interprets as “A”. 1100 0001 is the binary or 8-bit value that EBCDIC interprets as “A”. Buyer. The individual or organization who purchases the license to use the software package. Command. A single instruction to

20、 the computer. Commands are pre-defined and specific to the software. Computer Program. As used here, it is the set of computer instructions that make up the software pack- age. Physically, the package may contain more than one program. Conditional (CON). Information that must be supplied when relev

21、ant. Consumer software package. See soflware package. Cover. The carton, wrapper, or paper covering, in which the software product is contained prior to sale. This term does not include any clear plastic outer wrapper (such as “shrink-wrap”), normally discarded after opening, through which permanent

22、 packaging materials (e.g., a box or a binder) may be seen. Diskette. A portable, computer-readable read/write recording medium on which the program (and some- times the documentation) is stored and distributed for sale. It is also called a flexible disk or a floppy disk It and its permanent protect

23、ive cover are sometimes referred to as a flexible disk cartridge. Although the term diskette is used throughout this document, any other type or recording medium accessible to a com- puter can be substituted. EBCDIC (Extended Binary Coded Decimal Interchange Code). A symbolic interpretation of a uni

24、t of computer data made up of 8 bits. (See RSCII.) Environment. The configuration of hardware and operating system in which the computer program of the package operates. Essential (ESS). Information that must be supplied. Functions. The term used for the different things that the software can do. It

25、 consists of one or more com- mands used to accomplish a purpose. Manufacturer. The organization which develops or owns the rights to a software product and is responsible for its quality. The manufacturer may also have primary responsibility for maintenance, reproduction, cor- recting technical pro

26、blems, and answering user questions. Marketing organization. The organization which sells the software product. It may have responsibility for distribution and reproduction. It also may have responsibility for some maintenance, user training and help. 3 Optional (OPT). Information that may be suppli

27、ed at the discretion of the manufacturer or marketing organization. Package. Another term for software package. Pmgram. See computer program. Sections. The term used here for the divisions within a document that may be parts, chapters, sections, or paragraphs. Soffware package. A developed, tested,

28、and supported software product designed to carry out identified functions. It consists of one or more computer programs on a machine-readable recording medium and the associated documentation, packaged together for sale as a unit. Other equivalent terms are off-the-shelf software” and “ready-made so

29、ftware.” Support. (as used with reference to.software packages). Providing help and guidance to the user and cor- recting errors in software and documentation. Uninstdl. Reversing the installation of the software, enabling it to be installed elsewhere. It consists of re- moving software from the wor

30、k medium and restoring it to the diskette (or other medium) originally pur- chased because software with certain types of copy protection permit only a limited number of copies to be made. When installing this software, it can be copied to a “hard disk” for normal use, but the number of copies made

31、is recorded. “Uninstall” removes the work copy from the hard disk and adjusts the copy count on the source disk so that it may be copied again. User. The person who uses the software package. 4 SECTION 03 - KEY WORDS Following is a suggested list of key words or descriptors that can be used to ident

32、ity a software product, characterize its operations, summarize its functions, and classify the package for index storage, retrieval, and comparison purposes. A specific package may require more than one descriptor. This list is for refer- ence only since additional types of software may be developed

33、 and marketed. Accounting Analysis (specify type or subject) Assembler Business Management Communication Compiler Data Base Manager (indicate type, e.g., relational, hierarchical, file management) Decision Support (specify purpose) Design (specify type) Educational (include subject and level) Enhanc

34、er (e.g., software that enables other software to run better; software that documents other software; print modifiers) Expert System (specify subject) Financial Game (indicate type, e.g., arcade, chance, role playing, simulation, sport, strategy, simulation includes games like chess, poker, or bridg

35、e, or activities like flying or sailing) Graphics Integrated package (software that combines several otherwise independent functions) Integrator (software that enables other independent packages to be run simultaneously or software that enables data to transfer between packages) Job-Specific Languag

36、e - Computer (including those for programming, developing expert systems, artificial intelligence, and similar usage) Language - Translator or dictionary (e.g., English to French) Management Information Manufacturing Mathematical (specify type such as statistical formulas) Memory Resident Support Op

37、erating System Personal Management Personnel Management Publishing Shell (software that makes an operating system or software package more user-friendly) Spreadsheet Templates (for specified software) Tutorial (for specified purpose) utility Word Processor Writing Aid (e.g., dictionary, thesaurus, o

38、utline, usage anaIyzer 5 PART 1 - USER DOCUMENTATION SECTION 01 - GENERAL INFORMATION 1. Scope The user documentation portion of this technical report describes the information users need to know: (a) to understand the purpose, functions, and characteristics of the software; (b) to install and opera

39、te the product; (c) to identify the contractual rights and responsibilities of all parties. User documentation is an integral part of the product and should be provided at the time of purchase. 2. Application Part 1 of this technical report summarizes the minimum acceptable user documentation. Produ

40、ct develop- ers and manufacturers should provide additional information wherever and whenever needed. (For exam- ple, syntax and protocol documentation may be required for operating systems and computer language programs; other needs may exist with analysis and design software.) Within Part 1 of the

41、 report are descriptions of the many components of full user documentation. The com- ponents are not equally applicable to all software packages and the documentor can select those most appropriate to the product, being careful not to overlook something vital to a user. For some products, material d

42、escribed in a section may become full stand-alone manuals. For other products, little more than “load and run” instructions may be needed. 3. stxuctllre Section 02, “Components of User Documentation,” provides a comprehensive list of user documentation ele- ments. Subsequent sections enlarge and exp

43、and on many of these items. 4. Supplements As appropriate, issue supplements to all registered users to correct errors in software or in documentation. If software errors are known but not corrected, describe their potential impact and how they may be identi- fied and avoided. 7 SECTION02 - COMPONEN

44、TS OF USER DOCUMENTATION 1. Introduction The material in this section provides a summary of the information a user requires to operate a software package. Although based on IS0 9127, “User Documentation for Consumer Software Packages,” prepared by the International Standards Organization, it is enha

45、nced for the needs of individuals and corporations within the United States. The IS0 standard repeats similar information under more than one heading. This technical report follows the standard, and covers the information similarly. For the user, it may be repeated as necessary or placed only where

46、most appropriate. Some of this material is included as part of the Software Cover Information. Repeat it within the user docu- mentation-as part of the overview, installation, or any other section for which it is pertinent, or else incor- porate a copy of the cover document into the user manual. 2.

47、Reference Docum if it does not, explain the coding system to enable the user to identify the latest. (CON) 2.1.4. Date. Give the release date of the original and of this package version. (ESS) 2.1.5. Manufacturer or Marketing Organization. Give the name, address, and telephone number of the manufact

48、urer and of the marketing organization (if it has contractual obligations). (ESS) 8 2.1.6. Key Words. Provide words or descriptors that can be used to identify the package, characterize its operations, summarize its functions, and classify it for index storage, retrieval, and comparison purposes. (For example, WORD PROCESSOR or SPREAD SHEET; identify an INTEGRATED PACKAGE as such but also specify which majo