ANSI INCITS TR-8-1988 Information Processing Systems Technical Report - User Documentation for Consumer Software Packages (NOT AN AMERICAN NATIONAL STANDARD) (formerly ANSI X3 TR-8.pdf

1、ANSI INCITS TR-8-1988(formerly ANSI X3/TR-8-1988)Information Processing SystemsTechnical ReportUser Documentation forConsumer Software PackagesCopyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license

2、 from IHS-,-,-Published by American National Standards Institute 11 West 42nd Street, New York, New York 10036 Copyright 0 1990 by American National Standards institute All rights reserved. No part of this publication may be reproduced in any form, in an electronic retrieval system or otherwise, wit

3、hout prior written permission of the publisher. Printed in the United States of America Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-Information Processing Technical Report S

4、ystems X3/TR-8-88 User Documentation for Consumer Software Packages Developed by American National Standards Committee X3, Information Processing Systems Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted with

5、out license from IHS-,-,-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 held by the Computer and Business Equipment Manufacturers Association (CBEMA), 311 First

6、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 Reports are not standards, nor are they intended to be used as such. X3 Technical Reports a

7、re 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 premature to develop a standard due to a still changing technology, or inappropriate to devel

8、op 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 result in greater consistency and coherence of information processing systems. When the

9、 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 Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction

10、or networking permitted without license from IHS-,-,-TABLE OF CONTENTS PAGE PART 0 - 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 Sectio

11、n 01. General Information 7 1. Scope . 7 2. Application 7 3. Structure 7 4. Supplements . 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、. 12 1. Introduction 12 2. Format . 12 3. Content 12 4. Examples 13 Section 04. Preparing 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.

13、 Installation . 16 5. Modifying Software 16 6. Verification . 16 7. Conversion of Existing 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 Copyright Ameri

14、can National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-Section 07. Preparing a Command Guide . 21 1. Introduction 21 2.Format.2 1 3.Content 21 4. Examples 22 Section 08. Preparing a Technical Referen

15、ce . 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 the cover document approp- riately and instr

16、uct 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 illustrate the subject discussed. 5. strnctnre In gene

17、ral, 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 documentation (Cover Information). Parts 1 and

18、 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: ESS - Essential, information must be supplied

19、 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 Documentation. Major participants in the development

20、 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. Winger Valerie B. Winkler 2 Copyright American Na

21、tional Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-SECTION 02 - DEFINITIONS ASCII (American National Standard Code for Information Interchange ). A symbolic interpretation into control and graphic char

22、acters of a unit of computer data made up of 8 bits. (Also see EBCDIC.) ASCII and EBCDIC function similarly but interpret the 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”.

23、 Buyer. The individual or organization who purchases the license to use the software package. Command. A single instruction to 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- a

24、ge. Physically, the package may contain more than one program. Conditional (CON). Information that must be supplied when relevant. 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

25、not include any clear plastic outer wrapper (such as “shrink-wrap”), normally discarded after opening, through which permanent 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 docu

26、mentation) is stored and distributed for sale. It is also called a flexible disk or a floppy disk It and its permanent protective 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 t

27、o a com- puter can be substituted. EBCDIC (Extended Binary Coded Decimal Interchange Code). A symbolic interpretation of a unit 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. Esse

28、ntial (ESS). Information that must be supplied. Functions. The term used for the different things that the software can do. It 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 fo

29、r its quality. The manufacturer may also have primary responsibility for maintenance, reproduction, cor- recting technical problems, and answering user questions. Marketing organization. The organization which sells the software product. It may have responsibility for distribution and reproduction.

30、It also may have responsibility for some maintenance, user training and help. 3 Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-Optional (OPT). Information that may be supplied

31、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, and

32、 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 softw

33、are.” 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 work m

34、edium 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 is

35、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 Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo repr

36、oduction or networking permitted without license from IHS-,-,-SECTION 03 - KEY WORDS Following is a suggested list of key words or descriptors that can be used to identity a software product, characterize its operations, summarize its functions, and classify the package for index storage, retrieval,

37、 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 and marketed. Accounting Analysis (specify type or subject) Assembler Business Management Communication Compiler Data Base Manager

38、(indicate type, e.g., relational, hierarchical, file management) Decision Support (specify purpose) Design (specify type) Educational (include subject and level) Enhancer (e.g., software that enables other software to run better; software that documents other software; print modifiers) Expert System

39、 (specify subject) Financial Game (indicate type, e.g., arcade, chance, role playing, simulation, sport, strategy, simulation includes games like chess, poker, or bridge, or activities like flying or sailing) Graphics Integrated package (software that combines several otherwise independent functions

40、) Integrator (software that enables other independent packages to be run simultaneously or software that enables data to transfer between packages) Job-Specific Language - Computer (including those for programming, developing expert systems, artificial intelligence, and similar usage) Language - Tra

41、nslator or dictionary (e.g., English to French) Management Information Manufacturing Mathematical (specify type such as statistical formulas) Memory Resident Support Operating System Personal Management Personnel Management Publishing Shell (software that makes an operating system or software packag

42、e more user-friendly) Spreadsheet Templates (for specified software) Tutorial (for specified purpose) utility Word Processor Writing Aid (e.g., dictionary, thesaurus, outline, usage anaIyzer 5 Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo re

43、production or networking permitted without license from IHS-,-,-Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-PART 1 - USER DOCUMENTATION SECTION 01 - GENERAL INFORMATION 1. S

44、cope 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 operate the product; (c) to identify the contractual rights and responsibilities of all parties

45、. 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. Product develop- ers and manufacturers should provide additional information wherever and whene

46、ver 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 report are descriptions of the many components of full user documentation. The com- ponen

47、ts 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 described in a section may become full stand-alone manuals. For other products, little more

48、 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 expand on many of these items. 4. Supplements As appropriate, issue supplements to all regist

49、ered 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 Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reprod