Welcome to EverybodyWiki ! Nuvola apps kgpg.png Log in or create an account to improve, watchlist or create an article like a company page or a bio (yours ?)...

IEEE 1063

From EverybodyWiki Bios & Wiki



IEEE 1063 is a superseded standard promulgated by the Institute of Electrical and Electronics Engineers that provides minimum requirements for the structure, information content, and format of software user documentation (both printed and electronic).[1] It is a standard for the documentation phase of the Systems development life cycle.[2][3]

The last version of this standard (IEEE 1063-2001) was published in December 2001 and reaffirmed in September 2007.[1] It is an update on the IEEE 1063-1987 standard, which was also recognized as an American national standard (ANSI) and was widely used in the preparation of printed user manuals contributing to improvements in documentation quality.[4][5][6] This revision provided requirements for both printed and electronic documentation, whereas its predecessor from 1987 only considered printed documentation.[4]

In June 2011 it was superseded by the IEEE/ISO/IEC 26512-2011 standard, of which the latest (and currently active) revision is the ISO/IEC/IEEE 26512:2018 standard published in June 2018.[1][7][8][9] This is a standard with a wider scope that supports the interest of system users in having consistent, complete, accurate, and usable information and provides an overview of the information management processes that are relevant to the acquisition and supply of information for users.[9]

Contents of IEEE 1063-2001[edit]

1063-2001 - IEEE Standard for Software User Documentation is a document of approximately 30 pages available for purchase on the IEEE Standards Association website.

It is divided in the following sections:

  • Section 1: Overview
  • Section 2: Definitions
  • Section 3: Structure of software user documentation
  • Section 4: Information content of software user documentation
  • Section 5: Format of software user documentation

Essentially, the layout of the standard is organized according to the different aspects of user documentation: structure (section 3), information content (section 4) and format (section 5). Sections 3 and 4 are, as far as possible, media-independent. Requirements specific to either printed or electronic documentation are identified in section 5.

In general terms the content of this standard is similar to the previous IEEE 1063–1987 with the exception that one section was removed: "Identifying Required User Documents". Sections 3 to 5 were renamed in this revision but the content is similar to its predecessor.

Requirements of a successful software user documentation[edit]

This standard advocates that a successful software user documentation is "the result of proper audience identification, thoughtful software and document design, and good writing style, in addition to the structure, content, and format requirements addressed by this standard."[4]

Overall structure[edit]

A user documentation set may consist of one or more documents each of which may be one or more volumes. Well-structured documentation makes information available where it is needed without redundancy.

When a document addresses audiences with different needs one of this structures should be used:

  • Separate sections devoted to the needs of specific audiences.
  • Separate documents or document sets for each specific audience.

This standard differentiates two documentation usage modes (instructional or reference). When a document contains both modes, the two should be clearly distinguishable, either by separating them into different sections or by a different formatting.

  • Instructional mode: In this mode sections are organized to facilitate learning. Procedures are structured according to the user's tasks, related tasks are grouped in the same section and simpler more common, or initial tasks are presented before more complex, less utilized, or subsequent tasks.
  • Reference mode: In this mode documentation is arranged to facilitate random access to individual units of information. For example, a list of software commands or error messages should be arranged alphabetically.

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 should appear in the initial components. Specific warnings and cautions should appear on the same page or screen and immediately before the procedure or step that requires care.

Content[edit]

The following table enumerates required and optional structural, content, and format components of a good user documentation. The components may be arranged in this order in printed documentation.

Component Brief description Required?
Identification data (package label/title page) It must include at least the document title, document version, publication date, software product and version and issuing organization Yes
Table of contents It should list the sections of the document with an access point for each (its initial page number or an electronic link) Yes, in documents of more than eight pages after the identification data
List of illustrations The document may contain a list of tables, a list of figures, or a list of illustrations (including both tables and figures) Optional
Introduction Describes the intended audience, scope, and purpose for the document and includes a brief overview of the software purpose, functions, and operating environment Yes
Information for use of the documentation Information on how the documentation is to be used and an explanation of the notation Yes
Concept of operations Explains the conceptual background for use of the software (for example, by including a visual or verbal overview of the workflow) Yes
Procedures Instructions for performing procedures Yes (instructional mode)
Information on software commands Explains the formats and procedures for user-entered software commands Yes (reference mode)
Error messages and problem resolution Addresses all known problems so that the users can either recover from the problems themselves or clearly report them to the support team Yes
Glossary An alphabetical list of terms and definitions likely to be unfamiliar to the audience Yes, if documentation contains unfamiliar terms
Related information sources Information on accessing related information sources, such as a bibliography, list of references, or links to related web pages Optional
Navigational features Includes headings, sections and subsections, titles, page numbers, headers, footers, cross references, buttons... Yes
Index An alphabetical listing of keywords, graphics, or concepts with an access point for each Yes, in documents of more than 40 pages
Search capability Electronic documentation should provide a method of locating words in the text Yes, in electronic documents

Each individual document should be structured to begin with identification data, followed by a table of contents and an introduction; that is, the introduction is the first chapter or topic of the document.

Format[edit]

The documentation format includes the selected electronic or print media and presentation conventions for stylistic, typographic, and graphic elements.

If the software being documented has accessibility features that allow disabled people to use it, so must the documentation.

Consistency is a key component for a good software user documentation. Documentation should use consistent terminology. Special formatting used for highlighting important information or to identify new or changed content should also be consistent throughout the document. Similar material, such as sets of instructions, should be presented in a consistent format.

The size of the printed documentation or the equipment and software required to access the electronic documentation should be consistent with the capacity of the expected users’ work environment.

The user should be able to use the software and read the documentation simultaneously. Online documentation should be available for display at any time while the user is using the software.

Both printed and electronic documentation must be legible to the user. Font size, style and color must be chosen carefully and be legible against the expected background color. Electronic documentation should remain legible even if the user decides apply zoom or resize the window.

See also[edit]

  • Software user documentation

External links[edit]

References[edit]

  • IEEE standard for software user documentation. IEEE Computer Society. Software Engineering Standards Subcommittee., Institute of Electrical and Electronics Engineers., IEEE Standards Association., IEEE Standards Board. New York: Institute of Electrical and Electronics Engineers. 2001. ISBN 0-7381-3098-2. OCLC 50212424. Search this book on Amazon.com Logo.png
  • Jaimes Parada, Héctor Darío, dir. Posada Ballén, Yeimy Catalina (2017). Diseño de guía de auditoría para la documentación del usuario de software. OCLC 1137704518.CS1 maint: Multiple names: authors list (link) Search this book on Amazon.com Logo.png

Citations[edit]

  1. 1.0 1.1 1.2 "1063-2001 - IEEE Standard for Software User Documentation". IEEE Standards Association (IEEE-SA).
  2. Saleh, K. A. (Kassem A.),. Software engineering. Ft. Lauderdale, FL. ISBN 978-1-60427-674-9. OCLC 719387485.CS1 maint: Multiple names: authors list (link) Search this book on Amazon.com Logo.png
  3. Gao, Jerry. (2003). Testing and quality assurance for component-based software. Tsao, H.-S. J., Wu, Ye. Boston: Artech House. ISBN 1-58053-735-9. OCLC 53164802. Search this book on Amazon.com Logo.png
  4. 4.0 4.1 4.2 IEEE standard for software user documentation. IEEE Computer Society. Software Engineering Standards Subcommittee., Institute of Electrical and Electronics Engineers., IEEE Standards Association., IEEE Standards Board. New York: Institute of Electrical and Electronics Engineers. 2001. ISBN 0-7381-3098-2. OCLC 50212424. Search this book on Amazon.com Logo.png
  5. "1063-1987 - IEEE Standard for Software User Documentation". IEEE Standards Association (IEEE-SA).
  6. Over 200 U.S. Department of Energy Manuals Combined: CLASSICAL PHYSICS; ELECTRICAL SCIENCE; THERMODYNAMICS, HEAT TRANSFER AND FLUID FUNDAMENTALS; INSTRUMENTATION AND CONTROL; MATHEMATICS; CHEMISTRY; ENGINEERING SYMBIOLOGY; MATERIAL SCIENCE; MECHANICAL SCIENCE; AND NUCLEAR PHYSICS AND REACTOR THEORY. Jeffrey Frank Jones. Search this book on Amazon.com Logo.png
  7. "26512-2011 - IEEE/ISO/IEC Systems and software engineering -- Requirements for acquirers and suppliers of user documentation". IEEE Standards Association (IEEE-SA).
  8. "ISO - ISO/IEC/IEEE 26512:2011 - Systems and software engineering — Requirements for acquirers and suppliers of user documentation". International Organization for Standardization (ISO).
  9. 9.0 9.1 "ISO - ISO/IEC/IEEE 26512:2018 - Systems and software engineering — Requirements for acquirers and suppliers of information for users". International Organization for Standardization (ISO).

Category:Software documentation Category:Technical communication Category:IEEE standards


This article "IEEE 1063" is from Wikipedia. The list of its authors can be seen in its historical and/or the page Edithistory:IEEE 1063. Articles copied from Draft Namespace on Wikipedia could be seen on the Draft Namespace of Wikipedia and not main one.


Farm-Fresh comment add.png You have to Sign in or create an account to comment this article !