User Documentation: Customer Set Up or Upset? Richard Hodgkinson FISTC

User Documentation:
Customer Set Up
or Upset?
Richard Hodgkinson FISTC
Convenor ISO/IEC JTC 1/SC 7/WG 2
(Software & Systems Documentation)
[email protected]
BCS Hampshire - 2010/01/25
Today’s presentation
• An apology…Acronyms!
• Introduction:
• Why are International Standards important?
• How are ISO Standards produced?
• ISO/IEC? Æ JTC 1? Æ SC 7? Æ WG 2?
•Software & Systems Documentation:
• The story so far…
• Current projects,
• What’s in the S/W documentation standard?
…and there’s more!
BCS Hampshire - 2010/01/25
Curriculum Vitæ
•
•
•
•
1969: Graduated from Southampton College of Art,
1970 to 2004: IBM at Hursley Park,
1990: First ISO standards meeting (BSI PUKE),
2004: “Retired” from IBM and continue with ISO
participation in several ISO/IEC committees,
• Icons, symbols, accessibility and documentation,
• Participation in European standards via ETSI,
• Access symbols and EU M/376 Phase 1,
• Associate lecturer at University of Portsmouth,
• Fellow of Institute of Scientific & Technical
Communicators,
• Member of BCS Disability Group.
BCS Hampshire - 2010/01/25
BCS Hampshire - 2010/01/25
Why International Standards?
• International trade
• Safety
• Security
• Interoperability
• Consistency of operation
BCS Hampshire - 2010/01/25
Why International Standards?
• ISO = International Organisation for
Standardisation:
• Founded in 1947,
• Scope: “…to facilitate international exchange of goods
and services..”,
• “Standards are guideline documentation that reflects
agreements on products, practices or operations by
nationally or internationally recognised industrial,
professional, trade associations or governmental
bodies”,
• Standards are not compulsory unless mandated so by
an individual, an organisation or the market,
• Standards ensure consistency, but differentiation is still
possible via quality, performance and functionality.
BCS Hampshire - 2010/01/25
Photo of possible
“solution”...Bangkok adapter..
BCS Hampshire - 2010/01/25
How are standards produced?
• By consensus of the participating national experts
(e.g. BSI, ANSI, DIN...) reached by negotiation,
• Then, by review and ballot by national
organisations…larger body of experts and
organisational representatives.
• Iterative balloting process defined by ISO:
• New Project ballot requires approval, plus commitment
of minimum of five experts and editor from NBs,
• NP/NWI Æ WD Æ CD Æ FCD/DIS Æ FDIS Æ IS,
• Ballots conducted electronically and require minimum
66% approvals,
• “24/60 Month Rule”.
BCS Hampshire - 2010/01/25
ISO/IEC JTC 1/SC 7/WG 2?
• JTC 1 = Joint Technical Committee 1 of
&
• Founded in 1987,
• Responsible for most* Information Technology standards,
• Currently 15 Sub Committees…Security, Biometrics, Personal IDs,
Data management, User interfaces, Smart cards, etc.
• SC 7 = Software & Systems Engineering:
• 15 Working Groups…S/W Evaluation, Asset management, Quality
management, SWEBOK, Governance, Architecture, Testing, etc.
• WG 2 = Software & Systems Documentation:
• Published standards address development, design, management and
maintenance of software documentation,
• Meets twice yearly...occasionally alongside a Tech. Com. conference,
• Participating experts from Australia (ASTC), Canada (STC), Japan
(IPSJ), New Zealand (TCANZ), UK (ISTC) and USA (STC, PMI, IEEE
CS, & IEEE PCS)…
BCS Hampshire - 2010/01/25
WG 2 - The story so far
• ISO/IEC 6592:2000 - Guidelines for the documentation of
computer-based application systems.
• ISO/IEC 9127:1988 - User documentation and cover
information for consumer software packages.
• ISO/IEC 9294:2005 - Guidelines for the management of
software documentation.
• ISO/IEC 15910:1999 - Software user documentation
process (AS/NZS 4258:1994).
• ISO/IEC 18019:2004 - Guidelines for the design and
preparation of user documentation for application software.
• ISO/IEC 15289:2006 - Content of systems and software life
cycle process information products (Documentation).
BCS Hampshire - 2010/01/25
However…
• Published WG 2 standards were produced to
meet specific requirements,
• Contain many overlaps and gaps,
• WG 2 standards now include systems and
life-cycle documentation (e.g. ISO/IEC
15289),
• SC 7 agreement with IEEE-CS to adopt and
publish each others standards.
BCS Hampshire - 2010/01/25
Documentation Study Group
• Formed: SC 7 Montreal Plenary, May 2003,
• Chair: Pr. Y. Yamamoto (Keio University),
• Participants from WG 2 and IEEE CS,
• Reported: SC 7 Helsinki Plenary, May 2005.
• Recommendations:
• Create a new suite of documentation standards,
• Re-structure standards by intended users (designers,
managers, testers, suppliers, etc) and by documentation
types (software end-users and systems & life cycle
development),
• Re-use, update and rationalise existing WG 2 standards,
incorporating IEEE 1063:2001.
BCS Hampshire - 2010/01/25
New WG 2 Standards
Audience
User Documentation
Managers
ISO/IEC CD2 26511
Acquirers &
Suppliers
ISO/IEC FCD 26512
Testers & Reviewers
ISO/IEC 26513:2009
Designers &
Developers
ISO/IEC 26514:2008
Developers of user
documentation in an
Agile environment
ISO/IEC WD 26515
Information planners
Software &
Life Cycle
Documentation
ISO/IEC 26520
ISO/IEC 15289:2006
(Revision)
WG 2 Standards - Status
• ISO/IEC CD2 26511 – Requirements for managers of
user documentation (Australia),
• 2nd CD ballot underway.
• ISO/IEC FCD 26512 - Requirements for acquirers and
suppliers of user documentation (Canada),
• FCD ballot underway.
• ISO/IEC 26513:2009 - Requirements for testers and
reviewers of user documentation (UK).
• ISO/IEC 26514:2008 - Requirements for designers and
developers of user documentation (US)
• ISO/IEC 26515 – Developing user documentation in an
Agile environment (UK)
• NP approved, WD done, CD ballot 2010/06
BCS Hampshire - 2010/01/25
ISO/IEC 26514 “Pedigree”
• BS7649:1993 and BS 7830:1996:
• Individually prepared by BSI committee IST15/-/2 with ISTC input,
• Addressed printed and online documentation for application software,
• Withdrawn by BSI in 2005.
Ð
•ISO/IEC 18019:2004 – Guidelines for the design and preparation of user
documentation for application software:
• Prepared by WG 2 from updated contents of BS 7649 and BS 7830,
• Withdrawn by ISO in 2009.
Ð
•ISO/IEC 26514:2008 – Requirements for designers and developers of user
documentation:
•Updated content of ISO/IEC 18019 merged with relevant content of previously
published WG 2 standards and IEEE 1063:2001 – Standard for Software
Documentation.
BCS Hampshire - 2010/01/25
ISO/IEC 26514 - Key Points 1
• Provides guidance on all aspects of the design, development
and production and maintenance of software documentation,
• Primarily addresses software, but may be used for any
product, e.g. Hardware,
• Primarily addresses electronic “documentation”, with
additional guidance for printed documentation in Annex D,
• Contains consensus of best practices, knowledge and
expertise from professional organisations, business and
academia around the world,
• £234 (or £117 to BSI members).
BCS Hampshire - 2010/01/25
ISO/IEC 26514 - Key Points 2
• Contains normative requirements (“shall” clauses):
• Conformance can therefore be claimed,
• Can be specified in procurement and project requirements.
•Includes US “Section 508” documentation
accessibility requirements:
•Consistent with ISO 9241-171:2008 - Guidance on software
accessibility.
•The “core” standard for the WG 2 User
Documentation series (ISO/IEC 26511 to 26520).
BCS Hampshire - 2010/01/25
ISO/IEC 26514 - Structure
Content overview 1:
1 to 4 are “standard” ISO clauses which address the
Scope, Conformance, Normative references and
Definitions,
5 User documentation within the systems/software life
cycle process,
6 Project requirements, objectives and constraints,
7 Analysis and Design:
• Audience and task analysis, and user documentation
design,
8 Development and Review:
• Prototypes and drafts, evaluation of documentation and
testing.
BCS Hampshire - 2010/01/25
ISO/IEC 26514 - Structure
Content overview 2:
9 Production:
• Final assembly and review, approval, configuration,
management, updating and maintenance.
10 Structure of software user documentation:
• Overall structure, structure according to audience needs,
size of topics, components and their placement.
11 Information content:
• Completeness, accuracy, content of identification data,
information for use, concept of operations, information for
general use of the software, procedures and tutorials,
software commands, data entry fields and terminology.
BCS Hampshire - 2010/01/25
ISO/IEC 26514 - Structure
Content overview 3:
12 Presentation format of software user
documentation:
• Printed and electronic formats, media selection, context
sensitive information, accessibility, consistency of formats
and technology, layout of screens, legibility, formats for
lists, warnings, instructions, illustrations, use of colour,
navigation and use of icons.
BCS Hampshire - 2010/01/25
ISO/IEC 26514 - Structure
Content overview 4:
•Annex A - User documentation style guide content,
•Annex B - Writing style techniques for user
documentation,
•Annex C - User documentation style for translation
of documentation.
BCS Hampshire - 2010/01/25
ISO/IEC 26514 - Structure
Content overview 5:
•Annex D - Design and preparation of printed
documentation,
•Annex E - Process checklists,
•Annex F - Design checklist,
•Annex G - Checklist for user documentation,
•Annex H - Bibliography.
BCS Hampshire - 2010/01/25
ISO/IEC 26514 - Extract
Buying ISO Standards
www.iso.org/iso/home.htm
Buying IEC standards…
www.iec.ch/
Other WG 2 Activities
• Documentation for “Agile” s/w products.
• Dynamic Help system (Japan).
• (WG 26) ISO/IEC 29119 - Software Testing:
• Possibility of confusion regarding part 3
(Documentation of software testing) and
ISO/IEC 26513 (Testing of software
documentation)….care needed with the Scopes.
BCS Hampshire - 2010/01/25
Macon WG 2 Meeting
• Mercer University, Macon, GA, USA, 26th - 28th October 2009
• Experts present from Australia, Canada, Japan, UK & USA.
• Standards progressed:
• ISO/IEC 26511 (Managers): CD1 comments reviewed,
CD 2 prepared,
• ISO/IEC 26512 (Acquirers & Suppliers): CD 1 comments
reviewed, FCD prepared,
• ISO/IEC 26515 (Agile): WD discussed, CD ballot 2010/06,
• Dynamic Help System (Japan): Report on progress.
• Next WG 2 meeting: 23rd to 28th May 2010, Niigata, Japan
BCS Hampshire - 2010/01/25
…and there’s more!
ISO/IEC JTC 1/SC 7/WG 22 – Software &
Systems Engineering Consolidated
Vocabulary:
•Convenor: Annette D. Reilly (US STC),
•ISO/IEC 24765:2009 – Software and Systems
Engineering Vocabulary,
•SE VOCAB is freely available at:
http://pascal.computer.org/sev_display/index.action
BCS Hampshire - 2010/01/25
ISO/IEC 24765
http://pascal.computer.org/sev_display/index.action
…and more…
Standard symbols:
• ISO 7000:2004 – Graphical symbols for use on equipment
• Contains over 2000 symbols for use on agricultural and earthmoving
machines, automobiles, printing presses, photocopiers, mechanical
saws, lathes, etc.
• ISO/IEC 13251:2004 – Collection of graphical symbols for
use on office equipment,
• IEC 60417 Graphical symbols for use on equipment:
• Contains over 1000 symbols for use on electronic equipment,
• Available together with ISO 7000 as a database for CHF 300.
BCS Hampshire - 2010/01/25
…and more…
Standard icons:
• ISO/IEC 11581 - Icon symbols and functions:
• NOTE: Currently under revision by ISO/IEC JTC 1/SC 35,
• Part 1:2000 - Icons – General,
• Part 2:2000 - Object icons,
• Part 3:2000 - Pointer icons,
• Part 4 - Control icons (cancelled),
• Part 5:2004 - Tool icons,
• Part 6:1999 - Action icons,
• Part 40 (under discussion) Icon database.
•ISO/IEC 18035:2003 - Icon symbols and functions for controlling
multimedia software applications:
•Use in conjunction with ISO 14915-2:2003 - Software ergonomics for
multimedia user interfaces - Part 3: Multimedia navigation and control
BCS Hampshire - 2010/01/25
…and more…
Symbol design:
• ISO & IEC 80416 - Basic principles for graphical symbols for use on
equipment:
•
•
•
•
IEC 80416-1:2001 - Creation of symbol originals,
ISO 80416-2:2001 - Form and use of arrows,
IEC 80416-3:2002 - Guidelines for the application of graphical symbols,
ISO 80416-4:2005 - Guidelines for the adaptation of graphical symbols for use
on screens and displays (icons).
Symbol testing:
•ISO 9186-1:2007 - Graphical symbols – Methods for testing
comprehensibility,
•ISO 9186-2:2008 - Graphical symbols – Methods for testing perceptual
quality (in development),
•ETSI TR 070 (1993-06) - The Multiple Index Approach (MIA) for the
evaluation of pictograms,
BCS Hampshire - 2010/01/25
…and more…
Accessibility symbols:
•ISO/IEC TR 19765:2007 - Survey of icons and symbols that
provide access to functions and facilities to improve the use of
information technology products by the elderly and persons
with disabilities,
•ETSI EN 301 462 (2000-03) Symbols to identify
telecommunications facilities for deaf and hard of hearing
people,
•ETSI ES 202 432 (2006-10) Access symbols for use with
video content and ICT devices:
• ETSI TR 102 520 (2006-09) Access symbols for use with video
content and ICT devices – Development and evaluation.
BCS Hampshire - 2010/01/25
European Telecommunications
Standards Institute (ETSI)
User set-up and education:
•ETSI EG 202 416 (2006-12) User Interfaces; Setup
procedure design guidelines for mobile terminals and
e-services,
•ETSI EG 202 417 (2006-12) User education
guidelines for mobile terminals and services,
•Visit:
http://portal.etsi.org/STFs/STF_HomePages/STF285/
STF285.asp
BCS Hampshire - 2010/01/25
ETSI
ETSI HF STF 354: Guidelines and Tutorials
for Improving the User Experience of Realtime Communication Services:
• Project now under way
• Public comments welcomed
• Publication due February 2010
• Visit:
http://portal.etsi.org/STFs/STF_HomePages/STF354/
STF354.asp
BCS Hampshire - 2010/01/25
ETSI standards are free!
www.etsi.org/WebSite/homepage.aspx
R10Q!
[email protected]