GENERAL
Foreword
Introduction
Section 1. General
1.1 Scope
1.2 Informative references
1.3 Definitions
PROCESS
Section 2. Integrated design and development of software
products
2.1 Integrated development stages
2.2 Responsibilities for documentation activities
2.3 Local standards and procedures
2.4 Documentation processes
2.5 Sequence of documentation activities
Section 3. Project objectives, requirements and
constraints
3.1 General
3.2 Collect and interpret project requirements and
constraints
Section 4. Analysis
4.1 General
4.2 Collect details of users
4.3 Determine what documentation users need
4.4 Record users' needs for information
4.5 Produce the outline documentation plan
Section 5. Planning
5.1 General
5.2 Design the content, structure and style of each
document
5.3 Set the editorial standards
5.4 Design the physical presentation of each document
5.5 Design the complete package
5.6 Decide how the documents will be developed
5.7 Decide how the documents will be produced
5.8 Decide how the documents will be updated
5.9 Estimate costs
5.10 Prepare schedules
5.11 Revise the design
5.12 Write the documentation plan
5.13 Review the documentation plan
Section 6. Development and review
6.1 General
6.2 Prepare and issue first draft
6.3 Check and review drafts
6.4 Prepare subsequent drafts
6.5 Validation and field trials
6.6 Prepare master pages
Section 7. Production and distribution
7.1 General
7.2 Submit master pages for production
7.3 Package the documents and software
7.4 Check the finished documents and package
7.5 Archive the master versions
7.6 Distribute the product
Section 8. Evaluation and updating
8.1 General
8.2 Evaluate the documentation
8.3 Update the documentation
DETAILED DESIGN
Section 9. Document contents
9.1 General
9.2 Contents of awareness or appreciation documents
9.3 Contents of installation instructions
9.4 Contents of tutorials
9.5 Contents of quick reference documents
9.6 Contents of comprehensive reference documents
Section 10. Document structures
10.1 General
10.2 Structure of awareness or appreciation documents
10.3 Structure of installation instructions
10.4 Structure of tutorial documents
10.5 Structure of quick reference documents
10.6 Structure of comprehensive reference documents
10.7 Numbering schemes for pages, sections,
illustrations and tables
Section 11. Document writing styles
11.1 General
11.2 Writing style for awareness and appreciation
documents
11.3 Writing style for installation instructions
11.4 Writing style for tutorial documents
11.5 Writing style for quick reference documents
11.6 Writing style for comprehensive reference
documents
11.7 Types of illustration
Section 12. Document writing techniques
12.1 General
12.2 Writing techniques
12.3 Vocabulary
12.4 Technical terms
Section 13. Document presentation
13.1 General
13.2 Page layouts
13.3 Use of colour
13.4 Presentation of text
13.5 Presentation of lists, tables and notes
13.6 Presentation of illustrations
13.7 Special symbols and icons
13.8 Quality and durability of the finished documents
13.9 Binding
13.10 Packaging
13.11 Cover information
Section 14. Document contents lists and indexes
14.1 General
14.2 Contents lists
14.3 Indexes
Tables
1. Kinds of information for different learning stages
2. Types of documents and their uses
3. Methods of preparing master pages
4. Methods of producing multiple copies
5. The suitability of types of binding for different
needs
6. Example list of types of user
7. Example task list
8. Example task hierarchy
9. Example chart of users and tasks
10. Example of information needed by one user type
11. Example of grouping information into documents
12. Example entry for an outline documentation plan
13. The planning process
14. The development and review process
15. The production and distribution process
16. The evaluation and updating process
17. Example structure of an awareness document
18. Example structure of a getting started tutorial
19. Example structure of a tutorial for normal use
20. Example structures of quick reference documents
21. Example structure of a task-related comprehensive
reference document
22. Example structure of a software-related
comprehensive reference document
23. Example of a table used to illustrate a complicated
condition
24. Page grid for this British Standard
25. Page grid for an A5 page
26. Example A5 page
27. Example of the use of bold and italic and different
typefaces and sizes
ANNEXES
A. (informative) Bibliography
A.1 Reference books
A.2 Use of English
A.3 Preparing user documentation
A.4 Typography
B. (informative) Collected checklists
B.1 Project objectives, requirements and constraints
B.2 Analysis
B.3 Planning
B.4 Development and review
B.5 Production and distribution
Index
List of references