IEEE Std 1063-2001 IEEE Standard for Software User Documentation1. Overview This clause presents the scope, purpose, organization, and candidate uses of this standard. 1.1 Scope This standard provides minimum requirements for the structure, information content, and format of user This standard is intended neither to encourage nor discourage the use of either printed or electronic (online) media for documentation, or of any particular documentation development or management tools or methodologies. Users of this standard may want to develop a style manual for use within their own organizations to 1.2 Purpose This revision provides requirements for the structure, information content, and format of both printed and 1.3 Organization of the standard After Clause 2, this standard is organized according to the different aspects of user documentation: structure (Clause 3), information content (Clause 4), and format (Clause 5). In each clause, the requirements are media-independent, as far as possible. Requirements specific to either print or electronic media are identified as such, particularly in Clause 5. The order of clauses in this standard does not imply that the software user documentation should be developed in this order or presented to the user in this order. 1.4 Candidate uses The wording of each clause in this standard assists those intending to claim conformance with the standard. The term shall identifies mandatory requirements to claim conformance with this standard. The term should identifies an approach that is recommended, but not required, to claim conformance with this standard. The term may identifies an approach that is permitted within the limits of the standard, but not required to claim conformance with this standard. This standard may be included or referenced in contracts or similar agreements when the parties (called the acquirer and the producer or supplier) agree that the supplier will deliver documentation in accordance with the standard. This standard may also be adopted as an in-house standard by a project or organization that decides to produce documentation in accordance with the standard. Although this standard is intended for software documentation for end users, it may be applied to documentation produced for computer operators or system administrators who are not end users. This standard is meant to be tailored so that only necessary and cost-effective requirements are applied. Tailoring may take the form of specifying approaches to comply with its mandatory requirements, or altering its non-mandatory recommendations and approaches to reflect the particular software and documentation product more explicitly. Tailoring decisions made by the acquirer should be specified in the contract. 2. Definitions Throughout this standard, the term documentation refers to software user documentation. Use of the terminology in this standard is for ease of reference and is not mandatory for conformance with the standard. For the purposes of this standard, the following terms and definitions apply. IEEE 100, The Authoritative Dictionary of IEEE Standards Terms , Seventh Edition [B9] 1 , should be referenced for terms not defined in this clause. 2.1 action: Element of a step that a user performs to complete a procedure. 2.2 caution: Advisory in software user documentation that performing some action may lead to consequences 2.3 critical information: Information on the safe use of the software, the security of the information created with the software, or the privacy of the information created by or stored with the software. 2.4 document set: A collection of documentation that has been segmented into separately identified volumes or products for ease of distribution or use. 2.5 illustration: Graphic element set apart from the main body of text and normally cited within the main text. In this standard, the term illustration is used as the generic term for tables, figures, exhibits, screen captures, flow charts, diagrams, drawings, icons, and other graphic elements. 2.6 instructional mode: Usage mode that is intended to teach the use of software in performing tasks. 2.7 note: Helpful hint(s) and other information that may assist the user by emphasizing or supplementing important points of the main text. ( See also: warning and caution.) 2.8 procedure: Ordered series of steps that a user follows to do one or more tasks. 2.9 reference mode: Usage mode that is intended to provide quick access to specific information for software users who are generally familiar with the software functions. 2.10 software product: One or more computer programs together with any accompanying ancillary nonelectronic, non-mechanical items such as documentation and worksheets, delivered under a single name for use by others. 2.11 software user documentation: Electronic or printed body of material that provides information to users of software. 2.12 step: One element of a procedure. A step contains one or more actions. 2.13 style: Set of editorial conventions covering grammar, terminology, punctuation, capitalization, and layout of a software user document. 2.14 tutorial: Instructional procedure in which the user exercises software functions using sample data supplied with the software or documentation. 2.15 usage mode: Primary manner in which the document issuer expects the document to be used. This standard recognizes two usage modes: instructional and reference. 2.16 user: Person who employs software to perform a task. 2.17 warning: Advisory in software user documentation that performing some action may lead to serious or dangerous consequences. (See also: caution and note.) 3. Structure of software user documentation The structure of software user documentation, both printed and electronic, includes how it is organized into segments and in what order the segments are presented. Documentation may be structured into a single document or a document set of printed and/or electronic documents. The structure of software user documentation should aid the user in locating and understanding the information content. When a document set will address audiences with widely differing needs, at least one of the following structures shall be used: — Separate sections devoted to the needs of specific audiences. The audiences and their needs shall beidentified specifically in the introduction, allowing each user to identify the sections of interest. — Separate documents or document sets for each specific audience. Table 1 lists required and optional structural, content, and format components of the document. The components may be arranged in this order in printed documentation. The required components shall be included in software user documentation unless the information does not exist or is not applicable for a specific document. For example, a description of conventions may not be applicable in an overview document. The components may be renamed; for example, information suggested for the introduction could go in a section labeled “Preface.” 3.1 Overall structure of documentation A document set may consist of one or more documents, and each document of a document set may be one or more volumes. For example, a printed command manual might have one volume covering one half of the commands and a second volume covering the other half of the commands. Documents shall be structured into units with unique content. Well-structured documentation makes information available where it is needed without redundancy. For purposes of this standard, the following non-mandatory nomenclature is used for the structural parts of software user documentation. A printed document is structured into logical units called chapters, subdivided into topics, which may be subdivided into subtopics, and printed on physical units called Each page or screen shall be uniquely labeled (for example, with a page or topic number, or screen name or number). When viewed or printed, each topic in an electronic document should be identifiable as belonging to the parent document. For example, a status bar or header shows the document or file name. Printed documents shall be structured with no more than three levels of subdivision within a chapter. For example, a subtopic numbered 1.2.3.4 would be at the lowest level of subdivision. Electronic documents shall be structured so that information can be accessed with no more than three jumps (links) from the initial page of a topic (not counting any action required to open the document). Table 1—Components of software user documentation
The documentation structure, length of a chapter or topic, and amount of information presented on a page or screen (physical unit) depend on several considerations: The organization of documentation shall support its usage mode (instructional or reference). When a document contains both instructional and reference material, the two shall be clearly separated into different chapters or topics, or distinguished by formatting within the chapter or topic. Task-oriented instructional mode documentation shall include procedures structured according to the user’s tasks. Related tasks should be grouped in the same chapter or topic. Chapters and topics should be organized to facilitate learning by presenting simpler, more common, or initial tasks before more complex, less utilized, or subsequent tasks. For example, a list of software commands or error messages should be arranged alphabetically. 3.2 Initial components Each individual document shall be structured to begin with identification data (see 4.3), followed by a table of contents (see 5.7.1) and an introduction; that is, the introduction is the first chapter or topic of the document. The introduction shall describe the intended audience, scope, and purpose for the document and include a brief overview of the software purpose, functions, and operating environment. 3.3 Placement of critical information Critical information should be placed in a prominent location in the documentation. General warnings or cautions that apply throughout the use of the software or documentation shall appear in the initial components. Specific warnings and cautions shall appear on the same page or screen and immediately before the procedure or step that requires care. 4. Information content of software user documentation This clause specifies characteristics of information contained in user documentation (see 4.1 and 4.2), including completeness and accuracy. This clause also defines the required information for inclusion in user documentation (see 4.3 through 4.11). The information required in this clause shall be included in software user documentation unless the information does not exist or is not applicable for a specific document. The content of documentation is related to its usage mode. Users of software need documents either to learn about the software (instructional mode) or to refresh their memory about it (reference mode). Instructional mode documents may be either information- or task-oriented. Information-oriented documents instruct the user on the concepts and technical information needed to use the software properly (see 4.5). Task-oriented documents show the user how to complete procedures to reach a goal (see 4.6). Reference mode documentation may be context-sensitive and integrated in the software, for example, pop-up or drop-down lists of acceptable data values or commands. In either instructional or reference documentation, the content of documentation can be improved by the inclusion of examples and illustrations. 4.1 Completeness of information Documentation shall provide complete instructional and reference information for all critical software functions (software whose failure could have an impact on safety, or could cause large financial or social loss). Instructional mode documentation shall include complete information to enable performance of selected For example, if reference mode documentation covers a subset of software commands, it shall include all user-entered and systemdisplayed commands and error messages in that subset. 4.2 Accuracy of information Documentation shall accurately reflect the functions and results of the applicable software version. If the previous documentation version is no longer accurate, new documentation shall be available with software updates or upgrades. Documentation corrections and updates may be provided via a new manual, a read-me file or errata sheet, or a downloaded file from a web site. 4.3 Content of identification data Documentation shall contain unique identification data. The identification data shall include the following: Identification data shall appear on a package label, legible without opening the package, and on a title page. A package label is not required if the title page is legible without opening the package. Each document in a document set shall have a unique title page. For single-page documents, such as quick reference cards, the identification data may appear on the same page as the rest of the document. The title of the document should indicate its nature and scope and should not include abbreviations or acronyms unless they are familiar to the intended audience. If different versions of the software are available for different operating environments, the title page should specify the applicable operating environment(s), including version(s) of hardware, communications, and operating system(s). Other information, including document or software product part numbers, serial numbers, and restrictions on use, may be included on the package label and on the title page or following pages. The package label and pages immediately following the title page should include copyright and trademark notices, restrictions on copying or distributing the documentation, information for contacting the issuing organization (reader’s comments), warranties, contractual obligations or disclaimers, and general warnings and cautions. 4.4 Information for use of the documentation The documentation shall include information on how it is to be used (for example, help on help), and an explanation of the notation (a description of formats and conventions—see 5.8). At least one document in a document set shall identify all documents in the set by title and intended use, including recommendations on which members of the audience should consult which sections of the documentation. In document sets comprising many volumes or products, this information may be provided in a separate “road map” or guide to the document set. Documentation may include identification and discussion of notable changes from the previous version of the document set and the software. 4.5 Concept of operations Documentation shall explain the conceptual background for use of the software, using such methods as a visual or verbal overview of the process or workflow; or the theory, rationale, algorithms, or general concept of operation. Explanations of the concept of operation should be adapted to the expected familiarity of the users with any specialized terminology for user tasks and software functions. Documentation shall relate each documented function to the overall process or tasks. Conceptual information may be presented in one section or immediately preceding each applicable procedure. 4.6 Information for general use of the software Task-oriented instructional mode documentation shall include instructions for routine activities that are applied to several functions: These common procedures should be presented once to avoid redundancy when they are used in more complex functions. 4.7 Information for procedures and tutorials Instructional mode documentation provides directions for performing procedures. Instructions shall include preliminary information, instructional steps, and completion information. Preliminary information common to several procedures may be grouped and presented once to avoid redundancy. Preliminary information for instructions shall include the following: Relevant warnings, cautions, and notes shall immediately precede each applicable instructional step or group of steps. Instructional steps shall use the imperative mood for the user’s action. Instructional steps shall indicate the expected result or system response. Instructional steps shall include or provide references to documentation of the acceptable range, maximum length and applicable format, and unit of measurement of data fields for user-supplied data. Acceptable data formats and values are commonly documented through pop-up lists. Instructional steps shall include or provide references to explanations of error messages and recovery procedures. Instructional steps shall be presented in the order of performance. Alternative or repeated procedures should be clearly indicated, so the user can determine which alternate or repeated steps to perform or skip and where to rejoin the main procedure. Completion information for instructions shall indicate which is the last step in the procedure, how the user can determine whether the procedure has successfully completed, and how the user should exit from the procedure. 4.8 Information on software commands Documentation shall explain the formats and procedures for user-entered software commands, including required parameters, optional parameters, default options, order of commands, and syntax. Documentation may be provided on the development and maintenance of macros and scripts. Reference mode documentation shall contain a reference listing of all reserved words or commands. Examples should illustrate the use of commands. Documentation shall explain how to interrupt and undo operation during execution of a command and how to restart it, if possible. Documentation shall describe how to recognize that the command has successfully executed or abnormally terminated. 4.9 Information on error messages and problem resolution Documentation should address all known problems in using the software in sufficient detail such that the users can either recover from the problems themselves or clearly report the problem to technical support personnel. Reference mode documentation shall include each error message with an identification of the problem, probable cause, and corrective actions that the user should take. A quick reference card may address error messages by referring the user to more detailed reference documentation. The documentation on resolving problems shall also include contact information for reporting problems with software or its documentation and suggesting improvements. 4.10 Information on terminology Documentation shall include a glossary, if terms or their specific uses in the software user interface or documentation are likely to be unfamiliar to the audience. The glossary shall include an alphabetical list of terms and definitions. Documentation using abbreviations and acronyms unfamiliar to the audience shall include a list with definitions, which may be integrated with the glossary. Terms included in the glossary should also be defined on their first appearance in printed documentation. Electronic documentation may include links from terms to glossaries or explanations in secondary windows. 4.11 Information on related information sources Documentation may contain information on accessing related information sources, such as a bibliography, list of references, or links to related web pages. Related information sources and references may include the following: 5. Format of software user documentation The documentation format includes the selected electronic or print media and presentation conventions for stylistic, typographic, and graphic elements. This clause specifies formats for various documentation components. The format for reference mode documentation should be accessible and usable in the expected users’ work environment. The size of printed and bound reference documentation, or required equipment, electronic storage space, operating system software, and browsers to access online reference documentation, shall be consistent with the capacity of the expected users’ work environment. The documentation should be provided in media and formats that allow its use by those with a vision, hearing, or other physical limitation, if they are able to use the software and to perform the tasks supported by the software. Alternative documentation media and formats for users with physical limitations may require special adaptive software and equipment not provided with the user software or the user software documentation. 5.1 Consistency of terminology and formats Documentation shall use consistent terminology throughout a document set for elements of the user interface, data elements, field names, functions, pages, topics, and processes. Formatting conventions for highlighting information of special importance, such as warnings, cautions and notes, shall be applied consistently throughout the document set. The documentation may use special formatting to identify new or changed content. Formatting conventions may include colors, borders, indenting, spacing, and font variations. Similar material, such as sets of instructions, shall be presented in a consistent format. If documentation is adapted for use in another operating environment, language, or culture, a commonglossary and style guides for text and illustrations should be used to assist documentation developers and translators in maintaining consistency. Consideration should be given to selecting terminology, examples, graphics, and colors that are not culture-specific, so documentation can be more easily adapted, localized, or translated while preserving the intended meaning of the original. 5.2 Use of printed or electronic formats Whether or not electronic documentation is provided, the following documentation shall be presented in printed form: A description of how to print the electronic documentation should be included in both the electronic and the printed documentation. A means shall be provided for printing online documentation for those software systems designed for use when attached to a printer. The system should include software features designed to enable printing of electronic documentation. Online documentation shall be available for display at any time when user input to the software is possible. The user should be able to perform a function and read the relevant function-specific online documentation simultaneously. The user should be able to view the online documentation and navigate to related software functions during system operations. 5.3 Legibility Printed and electronic documentation shall be legible to the user, considering the distance between the user and the documentation in the expected work environment. Documentation shall use a font style and color that is legible against the expected background (paper color or screen background color). Online documentation shall remain legible if the user is able to enlarge, shrink, or reshape the screen or window. Uppercase (all capital) letters shall not be used for continuous text of more than 25 words. Text, including text in illustrations, shall be no smaller than 3 mm (approximately 7.5 points). Online documentation should be legible in the users’ expected work environment, which includes the anticipated combination of computer monitor or display and software graphics drivers. Legibility may be affected by output devices (monitors and printers) that are monochrome, have limited resolution, render colors differently, or support a limited range of colors. Some output devices may apply substitute fonts or special characters if the specified font is not available. Distinctions that depend on more than two gradations of colors or shades of gray may not be visible. Because some users cannot distinguish between colors, documentation should provide text cues rather than using colors such as red and green as the only way to convey meaning. 5.4 Formats for warnings, cautions, and notes Warnings, cautions, and notes shall be displayed in a consistent format that is readily distinguishable from ordinary text or instructional steps. The flag word (for example, warning, caution, or note ) shall precede the accompanying text. The term notes hall not be used to identify hazards. Warnings and cautions shall be identified by consistent and distinct graphics symbols, for example, an exclamation point or lightning bolt inside a triangle. A warning or caution shall include the following parts: 5.5 Format for instructions Instructional steps shall be consecutively numbered. A consistent numbering or lettering convention should be established for substeps or actions, alternative steps, and repeated procedures. 5.6 Formats for representing user interface elements Graphical user interface (GUI) elements of the software, such as buttons, icons, variable cursors and pointers; special uses of keyboard keys or combinations of keys; and system responses shall be represented in documentation by consistent graphic or typographical formats so that the various elements are each distinguished from the text. Documentation should include a representation of the element, its purpose, and an explanation of its action (functional consequence), with examples of actual operational instances. Online documentation may include pop-up text labels for GUI elements. Documentation formats for user-entered commands or codes shall clearly distinguish between literals (to be input exactly as shown) and variables (to be selected by the user). Quotation marks should not be used in command representations unless the user should input them literally. Documentation should address variations in keyboards or data entry devices in the expected users’ work environment. 5.7 Formats for documentation features for accessing information Documentation shall contain features to provide access to information, including a table of contents; a list of figures, tables, or illustrations; an index; and electronic search capabilities. 5.7.1 Table of contents A table of contents shall immediately follow the identification data (see 4.3). The table of contents shall list the headings of the chapters or topics of a document with an access point for each (its initial page number or an electronic link). Documents with fewer than eight pages after the identification data may omit the table of contents. The table of contents may be comprehensive or simple. A comprehensive table of contents lists all chapter or topic titles (headings) down to the third level. A simple table of contents includes only the first-level headings. Documents with a simple table of contents may include secondary comprehensive tables of contents appearing at the beginning of each chapter or topic, or accessible through pop-ups, expandable lists, or secondary windows. Electronic documentation may display tables of contents in expandable and collapsible formats to provide top-level and detailed access to headings without excessive scrolling. At least one volume of a document set shall include a simple table of contents for all volumes in the set. The table of contents shall include all portions of the documentation, including front matter that follows the table of contents and back matter (for example, appendixes, glossary, and index). The headings in the table of contents shall be identical in wording to those in the document, including chapter or topic numbers. The format of the table of contents shall distinguish the hierarchy of headings by consistent typography or indentation. In printed documentation, the table of contents shall list the headings in the same order as in the text. For electronic documentation, the table of contents should order the headings according to browse sequence, task, topic type, or other logical criteria. 5.7.2 List of illustrations Documentation should contain a list of tables, a list of figures, or a list of illustrations (including both tables and figures) if the document contains more than five numbered illustrations and the illustrations are not visible at the same time as text references to them. The list of illustrations shall list the illustration numbers and titles with an access point for each (such as its initial page number or an electronic link). The titles in the list of tables, figures, or illustrations shall be identical in wording to those in the document, including table, figure, or illustration numbers. 5.7.3 Index An index is an alphabetical listing of keywords, graphics, or concepts with an access point for each. Printed documents more than 40 pages shall include an index, whose access points may be page numbers, topic numbers, illustration numbers, or references to another index entry. Electronic documents more than 40 topics shall include either a search tool (see 5.7.4) or an index whose access points are electronic links. Annex B provides guidance for indexing user documentation. An index entry may cross-reference another index entry; however, the referenced entry shall give an access point to the documentation and shall not point to a third index entry. 5.7.4 Search capability Electronic documentation shall provide a method of locating words in the text. Electronic search capabilities may include full text search of the document or document set; search for words in illustrations; keyword search; finding a text string in the current topic; a Boolean search; and the restriction of a search to specific chapters, topics, or pages. 5.8 Formats for features for navigation Features for navigation include chapter and topic headings; page or screen titles; chapter, title, page, and screen numbers; tabs; page headers and footers; bookmarks; jumps (links); cross references; navigational icons; and buttons. Features for navigation shall be provided such that users can determine their location within the printed or electronic document and all of the locations to which they can move from their current location. Documentation shall include explanations of system- and document-specific navigational features. Navigation features shall use consistent formats for typography such as underscored links, color, or graphics to distinguish them from plain text. Navigation features should remain accessible in a static location if electronic documentation allows scrolling through the text. Jumps (links) shall provide a clear indication of the destination of the link. For example, use “More troubleshooting tips” rather than “Click here.” Links should provide information that the user expects in one jump, rather than requiring a link to another link that has the sought information. If the destination is outside the documentation, the documentation should provide users with an alternate way of locating the information, in case the link has been broken or the destination removed. Links between related topics shall be bidirectional, so that whichever topic the users access first, they can jump to the related information on the other topic. Electronic reference mode documentation shall be accessible from the software it documents, and shall provide a clear means of exiting the documentation and returning to the software. Software may be linked to online help, tutorials, or reference mode documentation in various ways, such as the following: 5.9 Formats for illustrations Illustrations that accompany text should appear adjacent to their first reference in the text, so the associated text and illustration can be viewed simultaneously. In documentation with more than five illustrations, each illustration should have a unique number and title (see 5.7.2). Informal illustrations, referred to only once in the text or having no text, may be untitled and unnumbered. The format of illustrations of similar content shall be consistent for scale, screen size, fonts, line thickness, and use of color. In electronic documentation, illustrations should be sized so they are legible and viewable in their entirety, without scrolling, on the expected viewing device. Consider simplifying or showing only salient features of a large graphic so it is visible at one time without scrolling. Long tables that cannot fit on a single page shall repeat the table title and column or row headings on each page or two-page spread. Long tables that span multiple pages should also be identified with a sheet number, for example, “Table 15. Metric units (sheet 2 of 4).” Documentation that is intended for both print and electronic distribution should be logically complete, including illustrations and references to illustrations, in both media. Fewer illustrations may be needed in electronic documentation that allows links to the actual software screens. Representations of GUI elements in documentation should be consistent with the version of the software being documented. Annex A (informative) Bibliography [B1] Brockmann, R. J., Writing Better Computer Documentation: From Paper to Hypertext, John Wiley & Annex B (informative) Indexing software user documentation An index is an important information retrieval device and should be constructed in a way that makes it easy for users to locate the information they seek. This annex provides guidance on good practices for indexing software user documentation. Use words that users are likely to look up and list all the topics in the document. Thoroughly indexed software user documentation can have two to five entries per topic. Index the preface, the appendixes, warnings, cautions, and notes. In electronic documents, index non-textual items such as graphics and multimedia. Avoid overly general keywords and use descriptive terms for entries, placing the main word first. For example, for the text heading, “Using file manager,” use the index heading, “file manager, using.” Double-post entries. For example, the topic that appears as “saving files” and “files, saving” is double-posted. Use synonyms Indicate the importance of information by placing minor key words under major ones. Break up entries that have multiple references in the document into sub-entries that indicate which aspect of the topic is covered. Use detailed primary entries rather than secondary or tertiary entries. Optionally, identify major page references by marking the page number in bold. Optionally, for document sets, include a global index in addition to the indexes in the individual volumes. The global index provides users with the means of looking for information in a single index, instead of looking it up in the indexes of the individual documents. Give location references for each entry that include an abbreviation of the document title in addition to the page numbers. Index A B C D E F G H I J K L M N O P R S T U V W |