SANS 26514-2009 Systems and software engineering - Requirements for designers and developers of user documentation《系统和软件工程 用户文件的设计者和开发者用要求》.pdf

《SANS 26514-2009 Systems and software engineering - Requirements for designers and developers of user documentation《系统和软件工程 用户文件的设计者和开发者用要求》.pdf》由会员分享，可在线阅读，更多相关《SANS 26514-2009 Systems and software engineering - Requirements for designers and developers of user documentation《系统和软件工程 用户文件的设计者和开发者用要求》.pdf（158页珍藏版）》请在麦多课文档分享上搜索。

1、 Collection of SANS standards in electronic format (PDF) 1. Copyright This standard is available to staff members of companies that have subscribed to the complete collection of SANS standards in accordance with a formal copyright agreement. This document may reside on a CENTRAL FILE SERVER or INTRA

2、NET SYSTEM only. Unless specific permission has been granted, this document MAY NOT be sent or given to staff members from other companies or organizations. Doing so would constitute a VIOLATION of SABS copyright rules. 2. Indemnity The South African Bureau of Standards accepts no liability for any

3、damage whatsoever than may result from the use of this material or the information contain therein, irrespective of the cause and quantum thereof. ISBN 978-0-626-22972-6 SANS 26514:2009Edition 1 ISO/IEC 26514:2008Edition 1 SOUTH AFRICAN NATIONAL STANDARD Systems and software engineering Requirements

4、 for designers and developers of user documentation This national standard is the identical implementation of ISO/IEC 26514:2008, and is adopted with the permission of the International Organization for Standardization and the International Electrotechnical Commission. Published by SABS Standards Di

5、vision 1 Dr Lategan Road Groenkloof Private Bag X191 Pretoria 0001Tel: +27 12 428 7911 Fax: +27 12 344 1568 www.sabs.co.za SABS SANS 26514:2009 Edition 1 ISO/IEC 26514:2008 Edition 1 Table of changes Change No. Date Scope National foreword This South African standard was approved by National Committ

6、ee SABS SC 71C, Information technology Systems and software engineering, in accordance with procedures of the SABS Standards Division, in compliance with annex 3 of the WTO/TBT agreement. This SANS document was published in August 2009. Reference numberISO/IEC 26514:2008(E)ISO/IEC 2008INTERNATIONAL

7、STANDARD ISO/IEC26514First edition2008-06-15Systems 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 SANS 26514:2008This s tandard may on

8、ly be used and printed by approved subscription and freemailing clients of the SABS .ISO/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 ar

9、e embedded are licensed to and installed on the computer performing the editing. In downloading 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 Incorpo

10、rated. Details of the software products used to create this PDF file can be found in the 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

11、a problem relating to it is found, please inform the Central Secretariat at the address 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 mechani

12、cal, including photocopying and microfilm, without permission in writing from either ISO 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.o

13、rg Published in Switzerland ii ISO/IEC 2008 All rights reservedSANS 26514:2008This s tandard may only be used and printed by approved subscription and freemailing clients of the SABS .ISO/IEC 26514:2008(E) ISO/IEC 2008 All rights reserved iiiContents Page Foreword viii Introduction . ix 1 Scope . 1

14、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 within the systems/software life cycle. 10 6 Project requirements, objectives, and constraints . 13 6.1 Project objectives . 13 6.2 User

15、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 Users and usability objectives 17 6.5 Interviewing technical contacts and other experts . 19 6.6 Project planning 19 6.6.1 Quality manage

16、ment. 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 localization and customization . 24 6.7 Documentation proposal . 24 7 Analysis and design . 25 7.1 Audience and task analysis. 25 7.1.1 Audience

17、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 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

18、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 Documentation 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

19、.2 Approval 40 9.3 CM. 41 SANS 26514:2008This s tandard may only be used and printed by approved subscription and freemailing clients of the SABS .ISO/IEC 26514:2008(E) iv ISO/IEC 2008 All rights reserved9.4 Updating and maintenance 41 10 Structure of documentation. 41 10.1 Overall structure of docu

20、mentation 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 User documentation components. 46 10.5 Placement of user doc

21、umentation 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 identification data 48 11.4 Information for use of the documentation4

22、9 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 information for procedures .53 11.7.4 Tutorials . 54 11.8 Informati

23、on 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 information sources 57 11.14 User-supplied content 58 12 Pr

24、esentation 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 applications displays 63 12.4 Context-sensitive information . 63

25、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 without unnecessary device references . 65 12.5.5 Provide do

26、cumentation 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 Formats for information area (text) . 69 12.8.5 Formats for he

27、adings . 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 SANS 26514:2008This s tandard may only be used and printed by approved subscription and f

28、reemailing clients of the SABS .ISO/IEC 26514:2008(E) ISO/IEC 2008 All rights reserved v12.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.

29、13.1 Using formats 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.

30、14.2 Menus. 78 12.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 8

31、1 12.18.2 Level of 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

32、and signposts . 85 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.

33、4 Grammar and usage . 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 in

34、structions. 96 B.7 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

35、.3 Style for translation 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 SANS 26514:2008This s tandard may only be used and printed by approved subscription and freemaili

36、ng clients of the SABS .ISO/IEC 26514:2008(E) vi ISO/IEC 2008 All rights reservedAnnex E (informative) 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

37、. 121 Annex G (informative) Requirements clauses and checklist for documentation products 127 Bibliography . 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

38、 of audiences for part of an order fulfillment system26 Figure 4 Sample of an audience hierarchy26 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.4

39、4 Figure 9 Using information type and usage to determine delivery method.45 Figure 10 Sample presentation 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 1

40、4 Sample links to related information .58 Figure 15 Sample grid for a help system navigator and 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

41、 an A5 page .108 List of Tables Table 1 Audience mapping matrix.30 Table 2 Components of documentation 46 SANS 26514:2008This s tandard may only be used and printed by approved subscription and freemailing clients of the SABS .ISO/IEC 26514:2008(E) ISO/IEC 2008 All rights reserved viiTable 3 Example

42、 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 . 62 Table 6 Examples of access methods 64 Table B.1 Example of conditions presented as a table. 91 Table D.1 Methods of producing mu

43、ltiple copies 103 SANS 26514:2008This s tandard may only be used and printed by approved subscription and freemailing clients of the SABS .ISO/IEC 26514:2008(E) viii ISO/IEC 2008 All rights reservedForeword ISO (the International Organization for Standardization) and IEC (the International Electrote

44、chnical 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 organization to deal with particular fields of technical

45、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 technology, ISO and IEC have established a joint technical c

46、ommittee, 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 adopted by the joint technical committee are circulat

47、ed 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 subject of patent rights. ISO and IEC shall not be held res

48、ponsible 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. SANS 26514:2008This s tandard may only be used and printed by approved subscription and freemail

49、ing clients of the SABS .ISO/IEC 26514:2008(E) ISO/IEC 2008 All rights reserved ixIntroduction 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 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 pro