International Standards for Software & Systems Documentation Ralph E. Robinson R 2 Innovations

Personal Bio Associate Fellow of STC & Senior Member of the Toronto Chapter Member of the STC Standards Council since years of experience in documenting ISO standards Canadian Delegate of the Standards Council of Canada on ISO/IEC JTC 1/SC 7/WG 2

Topics to be Covered International Standards, who cares? How are standards developed? A look at ISO/IEC JTC 1/SC 7/WG 2 Documentation standards exist? The future of documentation standards and opportunities for technical communicators

Why do we need standards? Purchasing requirements for businesses and organizations Legislation requirements (e.g. for safety) Consistency of use…improve usability and reduce training costs Provide guidance on “best practices” and reflect industry consensus Connectivity of products

A Case in Point

The standards process Need for an international standard is identified A Standards Sub Committee (SC) or Working Group (WG) prepares a New Work Item (NWI) or New Proposal (NP) Subsequent NP ballot cycles to SC National Bodies (NBs), then JTC 1 NB members Ballot requires 66% majority of “P” members & 5 members committed to active participation for acceptance

How are standards prepared? ISO standards are drafted using an ISO-specified template in Microsoft Word established by an ISO Directive Documents distributed and ballots conducted electronically Ballot cycles consists of NP/NWI, WD, CD, FCD/DIS, FDIS, leading to the IS publication Cycles repeated if ballot unsuccessful, e.g. 1st CD, 2nd CD, 3rd CD Projects automatically cancelled by ISO if not regularly progressed

Who is involved? Participating “Experts” represent their National Bodies are drawn from: Manufacturers National government organisations National standards organisations Industry consortia Professional organisations Academia

ISO/IEC JTC 1/SC 7/WG 2 JTC 1 Joint Technical Committee 1 – IT Standards  SC 7 Software & Systems Engineering oWG 2 Software & Systems Documentation WG 2’s Scope “Development of standards for the documentation of software systems”

ISO/IEC JTC 1/SC 7/WG 2 WG 2 experts are members of professional organisations (STC, ISTC, TCANZ, IEEE-CS) WG 2 experts represent USA, UK, Japan, Canada, Australia, and New Zealand national bodies Other experts participate via or through their national bodies

WG 2 Meeting in Helsinki, Finland May 2005

ISO/IEC JTC 1/SC 7/WG 2 Two international meetings held each year Liaison to CEN Workshop on Accessible Documentation (European) SC 7 web site at WG 2 web site at

Benefits of WG 2 Standards WG 2 standards Can be used for all forms of product documentation…not just software products Can be used in part or in whole Contain recommendations (guidelines) and not requirements Contain the consensus of best practices and guidelines developed by the direct participation and contributions of professional technical communicators from around the world Maintained by revisions or “re-confirmations”

Current WG 2 Standards ISO/IEC 9127: User documentation and cover information for consumer software packages ISO/IEC TR 9294: Guidelines for the management of software documentation ISO/IEC 15910: Software user documentation process (reconfirmed 2004)  Adapted from AS/NZS 4258:1994

Current WG 2 Standards ISO/IEC 18019: Guidelines for the design and preparation of user documentation for application software  Developed from BS 7649:1993 and BS 7830:1996 (withdrawn 2005) ISO/IEC FDIS Content of systems and software life cycle process information products (Documentation)

WG 2 Standards and User Documentation Development Defining Documentation  Deciding the most appropriate forms of documentation and the types of guidance that could be provided (18019) Setting Objectives  Collecting the project requirements (usability, accessibility, translation, packaging, standards, legal, costs, quality, approvals, resources, etc) and preparing the documentation proposal (9127/15910/18019) Planning  Creating the documentation plan and conducting reviews (15910/18019)

WG 2 Standards and User Documentation Development Analysis & Design  Identifying audiences, tasks, information, usability & accessibility, the document suite, document structures and style guides ( Annex F (Writing style guides)) Development & Review  Preparation, review and updating of the draft. Preparation of the document masters, localization, translation and archiving (18019) Evaluation & Updating  Evaluation and updating of the documentation ( Annex C (Evaluation))

WG 2 Standards and User Documentation Development Design of the documentation  Copyright and version details, documentation overview, process and task descriptions, explanations, messages, definitions, concepts, navigation, presentation, icons and illustrations (9127 & Annexes B (Design checklist) & E (Printed documentation)).

WG 2 – What’s next? SC 7 Study Group on User Documentation Standards Established at SC 7 Montreal Plenary (May 2003) Reported on at SC 7 Helsinki Plenary (May 2005)  Recommended restructuring and revision of S/W documentation standards based upon user’s needs Work already underway in WG 2, but help is needed  Current standards will not be revised, but content (including IEEE 1063) will be revised and re-used in a new suite

New WG 2 Standards Target Audience User Documentation Software & Life Cycle Documentation ProjectEditorPriorityProjectEditorPriority Documentation Managers ISO/IEC Australia (NWI) 1ISO/IEC New Zealand 2 Documentation Acquirers & Suppliers ISO/IEC tbd 4ISO/IEC tbd 4 Documentation Testers & Assessors ISO/IEC United Kingdom 2ISO/IEC tbd 3 Documentation Designers & Developers ISO/IEC USA (NWI) 1ISO/IEC Canada 3

Interested? “What’s in this for me?” No pay! Opportunity to contribute your expertise and experiences to the content of standards which have the potential to become future requirements for your business Advance knowledge of future documentation standards Access to copies of current documentation standards Opportunity to work with the international technical communication community Improved professional profile

QUESTIONS?