1、BS ISO/IEC 26514:2008 ICS 35.080 NO COPYING WITHOUT BSI PERMISSION EXCEPT AS PERMITTED BY COPYRIGHT LAW BRITISH STANDARD Software and systems engineering Requirements for designers and developers of user documentationThis British Standard was published under the authority of the Standards Policy and
2、 Strategy Committee on 31 July 2008 BSI 2008 ISBN 978 0 580 58205 9 Amendments/corrigenda issued since publication Date Comments BS ISO/IEC 26514:2008 National foreword This British Standard is the UK implementation of ISO/IEC 26514:2008. It supersedes BS 7137:1989 and BS ISO/IEC 18019:2004 and BS I
3、SO/ IEC 6592:2000 which is withdrawn. The UK participation in its preparation was entrusted to Technical Committee IST/15, Software and systems engineering. A list of organizations represented on this committee can be obtained on request to its secretary. This publication does not purport to include
4、 all the necessary provisions of a contract. Users are responsible for its correct application. Compliance with a British Standard cannot confer immunity from legal obligations.BS ISO/IEC 26514:2008 BS ISO/IEC 26514:2008Reference number ISO/IEC 26514:2008(E) ISO/IEC 2008INTERNATIONAL STANDARD ISO/IE
5、C 26514 First edition 2008-06-15 Systems and software engineering Requirements for designers and developers of user documentation Ingnierie du logiciel et des systmes Exigences pour les concepteurs et les dveloppeurs de la documentation de lutilisateur BS ISO/IEC 26514:2008 BS ISO/IEC 26514:2008 ISO
6、/IEC 26514:2008(E) PDF disclaimer This PDF file may contain embedded typefaces. In accordance with Adobes licensing policy, this file may be printed or viewed but shall not be edited unless the typefaces which are embedded are licensed to and installed on the computer performing the editing. In down
7、loading this file, parties accept therein the responsibility of not infringing Adobes licensing policy. The ISO Central Secretariat accepts no liability in this area. Adobe is a trademark of Adobe Systems Incorporated. Details of the software products used to create this PDF file can be found in the
8、 General Info relative to the file; the PDF-creation parameters were optimized for printing. Every care has been taken to ensure that the file is suitable for use by ISO member bodies. In the unlikely event that a problem relating to it is found, please inform the Central Secretariat at the address
9、given below. COPYRIGHT PROTECTED DOCUMENT ISO/IEC 2008 All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm, without permission in writing from either ISO
10、 at the address below or ISOs member body in the country of the requester. ISO copyright office Case postale 56 CH-1211 Geneva 20 Tel. + 41 22 749 01 11 Fax + 41 22 749 09 47 E-mail copyrightiso.org Web www.iso.org Published in Switzerland ii ISO/IEC 2008 All rights reservedBS ISO/IEC 26514:2008 BS
11、ISO/IEC 26514:2008 ISO/IEC 26514:2008(E) ISO/IEC 2008 All rights reserved iii Contents Page Foreword viii Introduction . ix 1 Scope . 1 2 Conformance. 3 2.1 Application of conformance 3 2.2 Conformance situations. 3 3 Normative references . 4 4 Terms and definitions. 4 5 User documentation process w
12、ithin the systems/software life cycle. 10 6 Project requirements, objectives, and constraints . 13 6.1 Project objectives . 13 6.2 User documentation requirements and constraints . 14 6.3 Project goals and constraints . 15 6.3.1 Project infrastructure and tools 16 6.3.2 Schedule constraints 16 6.4 U
13、sers and usability objectives 17 6.5 Interviewing technical contacts and other experts. 19 6.6 Project planning 19 6.6.1 Quality management. 20 6.6.2 Version control and change control . 21 6.6.3 Availability of resources 21 6.6.4 Schedules 22 6.6.5 Cost estimating . 23 6.6.6 Planning for localizati
14、on and customization . 24 6.7 Documentation proposal . 24 7 Analysis and design . 25 7.1 Audience and task analysis. 25 7.1.1 Audience analysis. 25 7.1.2 Audience profiles 27 7.1.3 Task analysis. 28 7.2 User documentation design 30 7.2.1 Designing for use of content . 31 7.2.2 Designing formats 31 8
15、 Development and review 32 8.1 Prototypes and drafts. 32 8.1.1 CM during development. 33 8.1.2 Development of translated and localized documentation 33 8.2 Evaluation of documentation 34 8.2.1 Other roles in evaluation of documentation quality 35 8.2.2 Documentation review procedures. 36 8.3 Documen
16、tation testing. 38 8.3.1 Types of documentation tests. 38 8.3.2 Usability tests 39 9 Production . 40 9.1 Final assembly and review 40 9.2 Approval 40 9.3 CM. 41 BS ISO/IEC 26514:2008 BS ISO/IEC 26514:2008 ISO/IEC 26514:2008(E) iv ISO/IEC 2008 All rights reserved9.4 Updating and maintenance 41 10 Str
17、ucture of documentation. 41 10.1 Overall structure of documentation 42 10.1.1 Structure of instructional mode documentation 43 10.1.2 Structure of reference mode documentation. 43 10.2 Structure of documentation according to audience needs 43 10.3 Size of topics in onscreen documentation. 45 10.4 Us
18、er documentation components. 46 10.5 Placement of user documentation components 47 10.5.1 Initial components 47 10.5.2 Placement of critical information 47 11 Information content of user documentation 47 11.1 Completeness of information 48 11.2 Accuracy of information. 48 11.3 Content of identificat
19、ion data 48 11.4 Information for use of the documentation49 11.5 Concept of operations 50 11.6 Information for general use of the software.51 11.7 Information for procedures and tutorials . 52 11.7.1 Preliminary information for procedures . 52 11.7.2 Procedural steps . 52 11.7.3 Completion informati
20、on for procedures .53 11.7.4 Tutorials . 54 11.8 Information on software commands . 54 11.9 Explanations of data entry fields. 55 11.10 Content of error messages and problem resolution . 55 11.11 Content of warnings and cautions 56 11.12 Information on terminology . 57 11.13 Information on related i
21、nformation sources 57 11.14 User-supplied content 58 12 Presentation format of documentation. 59 12.1 General . 59 12.2 Use of printed or on-screen formats. 60 12.3 Selection of appropriate media and format 61 12.3.1 Comparison of media . 61 12.3.2 Relationship of information displays to the applica
22、tions displays 63 12.4 Context-sensitive information . 63 12.5 Accessible documentation. 64 12.5.1 Provide understandable documentation 64 12.5.2 Provide user documentation in accessible electronic form. 65 12.5.3 Provide text alternatives in on-screen documentation . 65 12.5.4 Write instructions wi
23、thout unnecessary device references . 65 12.5.5 Provide documentation on accessibility features . 65 12.6 Consistency of formats 65 12.7 Consistency of terminology. 66 12.8 Layout of screens and pages. 67 12.8.1 Grids . 67 12.8.2 Non-scrolling areas. 68 12.8.3 Arrangement of windows . 68 12.8.4 Form
24、ats for information area (text) . 69 12.8.5 Formats for headings . 69 12.8.6 Blank space and borders . 69 12.8.7 Vertical spacing. 70 12.9 Legibility. 70 12.9.1 Typefaces and text size 71 12.9.2 Highlighting text 71 12.9.3 Lines of text . 72 12.10 Formats for lists 72 BS ISO/IEC 26514:2008 BS ISO/IE
25、C 26514:2008 ISO/IEC 26514:2008(E) ISO/IEC 2008 All rights reserved v 12.11 Formats for representing user interface elements 73 12.11.1 Representing control and command input 73 12.11.2 Representing special keyboard keys 73 12.12 Use of color . 74 12.13 Navigational features 75 12.13.1 Using formats
26、 to indicate position within a topic . 75 12.13.2 Finding the same information again. 76 12.13.3 Viewing topics in sequence. 76 12.13.4 Formats for active areas 76 12.13.5 Linking information 77 12.14 Documentation formats for finding information 77 12.14.1 Table of contents 77 12.14.2 Menus. 78 12.
27、14.3 List of illustrations 79 12.14.4 Index. 79 12.14.5 Search capability 80 12.15 Formats for warnings, cautions, and notes . 80 12.16 Format for instructions 81 12.17 Formats for user-supplied annotations 81 12.18 Formats for illustrations 81 12.18.1 When to use an illustration 81 12.18.2 Level of
28、 detail in illustrations 82 12.18.3 Identification of illustrations 82 12.18.4 Consistent presentation of illustrations. 82 12.18.5 Placement of illustrations 83 12.18.6 Illustrations of screen displays . 83 12.18.7 Illustrations of printed output 84 12.18.8 Tables. 85 12.19 Icons and signposts . 85
29、 12.19.1 When to use icons and signposts. 85 12.19.2 Design of icons and signposts 85 12.19.3 Displaying the names of icons 86 12.20 Documentation packaging. 87 Annex A (informative) User documentation style guide content 88 A.1 Writing style 88 A.2 Language . 88 A.3 Spelling 88 A.4 Grammar and usag
30、e . 88 Annex B (informative) Writing style and techniques for user documentation. 89 B.1 General. 89 B.2 Style for sentences. 90 B.3 Style for paragraphs. 94 B.4 Style for quick-reference information. 95 B.5 Style for installation instructions 95 B.6 Style for tutorials and task instructions. 96 B.7
31、 Style for describing user interface elements. 96 B.8 Style for descriptions and explanations. 96 B.9 Style for on-screen information 97 B.10 Style for lists . 97 Annex C (informative) User documentation style for translation and localization 98 C.1 General. 98 C.2 Terminology 98 C.3 Style for trans
32、lation 99 C.4 Cultural factors . 100 Annex D (informative) Design, development, and production of printed information 102 D.1 Introduction . 102 D.2 Design 102 D.3 Production phase 110 BS ISO/IEC 26514:2008 BS ISO/IEC 26514:2008 ISO/IEC 26514:2008(E) vi ISO/IEC 2008 All rights reservedAnnex E (infor
33、mative) Checklists for user documentation 114 E.1 Checklist for printed manuals 114 E.2 Checklist for online help 117 Annex F (informative) Requirements clauses and checklist for the documentation process . 121 Annex G (informative) Requirements clauses and checklist for documentation products 127 B
34、ibliography . 141 List of Figures Figure 1 Sample process of defining the usability goals for an electronic mail system 18 Figure 2 Sample contents list for a documentation proposal 25 Figure 3 Sample list of audiences for part of an order fulfillment system26 Figure 4 Sample of an audience hierarch
35、y26 Figure 5 Sample audience profile28 Figure 6 Sample task list for an electronic mail system 28 Figure 7 Sample task hierarchy.29 Figure 8 Using audience information needs to determine document content.44 Figure 9 Using information type and usage to determine delivery method.45 Figure 10 Sample pr
36、esentation of an example50 Figure 11 Sample overview for a software product module 51 Figure 12 Sample function description for a spreadsheet function .55 Figure 13 Sample definition of a term .57 Figure 14 Sample links to related information .58 Figure 15 Sample grid for a help system navigator and
37、 a topic window.68 Figure 16 Example of a contents list .78 Figure 17 Sample text menu .79 Figure 18 Use of two scales for screen displays .84 Figure D.1 Example of an A5 page grid 107 Figure D.2 Example of an A5 page .108 List of Tables Table 1 Audience mapping matrix.30 Table 2 Components of docum
38、entation 46 BS ISO/IEC 26514:2008 BS ISO/IEC 26514:2008 ISO/IEC 26514:2008(E) ISO/IEC 2008 All rights reserved vii Table 3 Example of procedures with the elements marked 53 Table 4 Sample Information Profile for one task and one audience . 61 Table 5 Advantages and disadvantages of various media . 6
39、2 Table 6 Examples of access methods 64 Table B.1 Example of conditions presented as a table. 91 Table D.1 Methods of producing multiple copies 103 BS ISO/IEC 26514:2008 BS ISO/IEC 26514:2008 ISO/IEC 26514:2008(E) viii ISO/IEC 2008 All rights reservedForeword ISO (the International Organization for
40、Standardization) and IEC (the International Electrotechnical Commission) form the specialized system for worldwide standardization. National bodies that are members of ISO or IEC participate in the development of International Standards through technical committees established by the respective orga
41、nization to deal with particular fields of technical activity. ISO and IEC technical committees collaborate in fields of mutual interest. Other international organizations, governmental and non-governmental, in liaison with ISO and IEC, also take part in the work. In the field of information technol
42、ogy, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1. International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2. The main task of the joint technical committee is to prepare International Standards. Draft International Standards
43、adopted by the joint technical committee are circulated to national bodies for voting. Publication as an International Standard requires approval by at least 75 % of the national bodies casting a vote. Attention is drawn to the possibility that some of the elements of this document may be the subjec
44、t of patent rights. ISO and IEC shall not be held responsible for identifying any or all such patent rights. ISO/IEC 26514 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information technology, Subcommittee SC 7, Software and systems engineering. BS ISO/IEC 26514:2008 BS ISO/IEC 26514:2008
45、 ISO/IEC 26514:2008(E) ISO/IEC 2008 All rights reserved ix Introduction Anyone who uses application software needs accurate information about how the software will help the user accomplish a task. The documentation may be the first tangible item that the user sees and therefore influences the users
46、first impressions of the software product. If the information is supplied in a convenient form and is easy to find and understand, the user can quickly become proficient at using the product. Hence, well-designed documentation not only assists the user and helps to reduce the cost of training and su
47、pport, but also enhances the reputation of the product, its producer, and its suppliers. Although software developers aim to design user interfaces that behave so intuitively that very little separate documentation is needed, this is rarely possible. Todays software offers increasingly robust functi
48、onality, not only within applications, but also across applications that intelligently exchange information with one another. Further, most software designs include underlying rules and calculations, or algorithms, that affect the results a user can obtain when using the software. Such underlying pr
49、ogramming mechanics are discernable by users, but only through laborious testing. For these reasons and more, user documentation remains an essential component of usable software products. Documentation is often regarded as something done after the software has been implemented. However, for high-quality software documentation, its development should be regarded as an integral part of the software life cycle process. If done properly, documentation or information management is a big
