ISO/IEC/IEEE 26515:2011
(Main)Systems and software engineering — Developing user documentation in an agile environment
Systems and software engineering — Developing user documentation in an agile environment
ISO/IEC 26515:2011 specifies the way in which user documentation can be developed in agile development projects. It is intended for use in all organizations that are using agile development, or are considering implementing their projects using these techniques. It applies to people or organizations producing suites of documentation, to those undertaking a single documentation project, and to documentation produced internally, as well as to documentation contracted to outside service organizations. ISO/IEC 26515:2011 addresses the relationship between the user documentation process and the life cycle documentation process in agile development. It describes how the information developer or project manager may plan and manage the user documentation development in an agile environment. It is intended neither to encourage nor to discourage the use of any particular agile development tools or methods.
Ingénierie du logiciel et des systèmes — Développement de la documentation de l'utilisateur dans un environnement agile
General Information
Relations
Standards Content (Sample)
INTERNATIONAL ISO/IEC/
STANDARD IEEE
26515
First edition
2011-12-01
Corrected version
2012-03-15
Systems and software engineering —
Developing user documentation in an
agile environment
Ingénierie du logiciel et des systèmes — Développement de la
documentation de l'utilisateur dans un environnement agile
Reference number
ISO/IEC/IEEE 26515:2012(E)
©
ISO/IEC 2012
©
IEEE 2012
---------------------- Page: 1 ----------------------
ISO/IEC/IEEE 26515:2012(E)
COPYRIGHT PROTECTED DOCUMENT
© ISO/IEC 2012
© IEEE 2012
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 ISO, IEC or IEEE at the respective
address below.
ISO copyright office IEC Central Office Institute of Electrical and Electronics Engineers, Inc.
Case postale 56 3, rue de Varembé 3 Park Avenue, New York
CH-1211 Geneva 20 CH-1211 Geneva 20 NY 10016-5997, USA
Tel. + 41 22 749 01 11 Switzerland E-mail stds.ipr@ieee.org
Fax + 41 22 749 09 47 E-mail inmail@iec.ch Web www.ieee.org
E-mail copyright@iso.org Web www.iec.ch
Web www.iso.org
Published in Switzerland
© ISO/IEC 2012 – All rights reserved
ii © IEEE 2012 – All rights reserved
---------------------- Page: 2 ----------------------
ISO/IEC/IEEE 26515:2012(E)
Contents Page
Foreword . iv
Introduction . v
1 Scope . 1
2 Conformance . 1
2.1 Application of conformance . 1
3 Normative references . 2
4 Terms and definitions . 2
5 User documentation processes in an agile environment . 4
5.1 Relationship between user and life cycle documentation processes . 4
5.2 Life cycle software documentation in an agile environment . 5
5.3 Life cycle documentation in agile development . 6
6 Management of information development in an agile environment . 6
6.1 Documentation management considerations for agile development . 6
6.2 Change management when moving to an agile development process . 7
6.3 Composition of agile development teams . 7
6.3.1 Communication in agile development teams . 8
6.3.2 Teams working in different locations . 8
6.4 Management of information development across teams using agile development . 9
6.5 Management of tasks across sprints . 9
6.5.1 Planning the project as a whole . 9
6.5.2 Sizing and resourcing each sprint . 10
6.5.3 Handling last-minute documentation changes . 11
6.6 Monitoring and analysing progress in an agile environment . 11
6.6.1 Status meetings . 11
6.6.2 Monitoring progress . 12
6.6.3 Rework and changing requirements . 13
6.7 Stakeholder involvement . 13
6.8 Improving the user documentation process in an agile environment . 14
6.8.1 Assessing customer satisfaction . 14
7 Developing user documentation in an agile environment . 14
7.1 What agile development means for information development . 14
7.2 Product design and developing the user documentation . 15
7.3 Design and development of user documentation in an agile environment . 16
7.3.1 Design techniques . 16
7.3.2 Information development tasks . 20
7.3.3 Planning of information units . 20
7.4 Testing and reviewing documentation in an agile environment . 20
7.4.1 Reviewing user documentation . 20
7.4.2 System test of documentation . 21
7.4.3 Usability testing of user documentation . 21
7.5 Translation and localisation of user documentation . 22
7.6 Production for manufacturing cycles . 22
Annex A (informative) Agile Development Practices . 23
Annex B (informative) Example interview questions . 25
Bibliography . 27
© ISO/IEC 2012 – All rights reserved
© IEEE 2012 – All rights reserved iii
---------------------- Page: 3 ----------------------
ISO/IEC/IEEE 26515:2012(E)
Foreword
ISO (the International Organization for 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 organization 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
technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.
IEEE Standards documents are developed within the IEEE Societies and the Standards Coordinating
Committees of the IEEE Standards Association (IEEE-SA) Standards Board. The IEEE develops its standards
through a consensus development process, approved by the American National Standards Institute, which
brings together volunteers representing varied viewpoints and interests to achieve the final product.
Volunteers are not necessarily members of the Institute and serve without compensation. While the IEEE
administers the process and establishes rules to promote fairness in the consensus development process, the
IEEE does not independently evaluate, test, or verify the accuracy of any of the information contained in its
standards.
International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2.
The main task of ISO/IEC JTC 1 is to prepare International Standards. Draft International Standards 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 called to the possibility that implementation of this standard may require the use of subject matter
covered by patent rights. By publication of this standard, no position is taken with respect to the existence or
validity of any patent rights in connection therewith. ISO/IEEE is not responsible for identifying essential
patents or patent claims for which a license may be required, for conducting inquiries into the legal validity or
scope of patents or patent claims or determining whether any licensing terms or conditions provided in
connection with submission of a Letter of Assurance or a Patent Statement and Licensing Declaration Form, if
any, or in any licensing agreements are reasonable or non-discriminatory. Users of this standard are
expressly advised that determination of the validity of any patent rights, and the risk of infringement of such
rights, is entirely their own responsibility. Further information may be obtained from ISO or the IEEE
Standards Association.
ISO/IEC/IEEE 26515 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information technology,
Subcommittee SC 7, Software and systems engineering, in cooperation with the Systems and Software
Engineering Committee of the IEEE Computer Society, under the Partner Standards Development
Organization cooperation agreement between ISO and IEEE.
In this corrected version, the cover pages, front matter, page headers and footers have been corrected to
reflect that ISO/IEC/IEEE 26515 is a joint development project under the Partner Standards Development
Organization cooperation agreement between ISO and IEEE.
© ISO/IEC 2012 – All rights reserved
iv © IEEE 2012 – All rights reserved
---------------------- Page: 4 ----------------------
ISO/IEC/IEEE 26515:2012(E)
Introduction
Anyone who uses application software needs accurate information about how the software will help the users
accomplish a task. The documentation may be the first tangible item that the user sees, and so influences the
first impressions the users have of the product. If the information is supplied in a convenient form and is easy
to find and understand, the users can quickly become proficient at using the product. Hence, well designed
documentation not only assists the users and helps to reduce the cost of training and support, but also
enhances the reputation of the product, its producer, and its suppliers.
Projects that implement agile development focus on providing rapid and frequent deliveries of high value
software. These methods often involve detailed planning only for the short term, and the implementation of
processes in parallel, rather than planning for an entire project in distinct phases.
Although agile development methods often advocate less life cycle documentation, the users of a software
product still expect and require quality user documentation to be provided with these software products.
Although the end results of the user documentation process are the same, the methods to get there may be
very different in an agile environment.
Agile development methods may lead to the production of less user documentation, but the user
documentation developed must be sufficient to meet the needs and requirements of the users. If the
deliverables of user documentation and associated life cycle documentation are agreed in a contractual
relationship between an acquirer and a supplier, then the deliverables that are produced are dictated by the
terms of the contract. In these circumstances, the user and life cycle documentation deliverables that are
agreed upon will depend on the demands of the acquiring organization regardless of the types of development
methodologies used to produce them.
Technical writers and other personnel involved in the production of user documentation should understand the
agile development processes used by their organization, and use the most effective agile development
methods to produce relevant and useful user documentation.
Because of the nature of agile development methods, the traditional means of developing the end user
documentation (both print and onscreen) as described in the current ISO/IEC 2651n family of International
Standards are not entirely applicable.
This International Standard was developed to assist users of ISO/IEC 15288:2008 (IEEE Std 15288:2008),
Systems and software engineering — System life cycle processes, or ISO/IEC 12207:2008 (IEEE Std
12207-2008), Systems and software engineering — Software life cycle processes, and ISO/IEC 26514,
Systems and software engineering — Requirements for designers and developers of user documentation
(also available as IEEE Std 26514-2010, IEEE Standard for Adoption of ISO/IEC 26514:2008, Systems and
Software Engineering — Requirements for Designers and Developers of User Documentation) and others in
the ISO/IEC 2651n family of International Standards. It provides requirements and guidance to technical
writers and related roles on how to adapt the processes described in the ISO/IEC 2651n family of International
Standards to develop quality user documentation.
This International Standard is independent of the agile development methods and tools that are used to
produce the software.
This International Standard will conform to ISO/IEC 12207:2008 (IEEE Std 12207:2008) as an implementation
of the user documentation part of 6.1: Documentation. The primary references for this International Standard
are ISO/IEC 26514:2008 and ISO/IEC 26513:2009.
© ISO/IEC 2012 – All rights reserved
© IEEE 2012 – All rights reserved v
---------------------- Page: 5 ----------------------
INTERNATIONAL STANDARD ISO/IEC/IEEE 26511:2012(E)
Systems and software engineering — Developing user
documentation in an agile environment
1 Scope
This clause presents the scope, purpose, organization, and candidate uses of this International Standard.
This International Standard supports the interest of technical writers and associated roles responsible for
producing user documentation for software and systems developed within an agile environment. This
International Standard takes a process standard approach to specify the way in which user documentation
can be developed in agile development projects.
This International Standard provides requirements on information management and documentation processes
appropriate for software projects that are using agile development methods.
Clause 5 covers the overall requirements for documentation in the software life cycle.
Clause 6 describes how the information development lead or project manager may plan and manage the user
documentation development team in an agile environment.
Clause 7 covers the relationship between the user documentation process and life cycle documentation
process in agile development.
This International Standard is intended neither to encourage nor to discourage the use of any particular agile
development tools or methods.
This International Standard provides guidance on processes appropriate for developers of user documentation
in software and systems projects that are using agile development methodologies. It will not be limited to the
development phase of the life cycle of user documentation, but includes activities throughout the user
documentation life cycle.
This International Standard is intended for use in all organizations that are using agile development, or are
considering implementing their projects using these techniques. It is assumed that users of this International
Standard have experience or general knowledge of traditional user documentation processes.
2 Conformance
This International Standard may be used as a conformance or a guidance document for projects and
organizations claiming conformance to ISO/IEC 15288:2008 (IEEE Std 15288-2008), Systems and software
engineering — System life cycle processes and/or ISO/IEC 12207:2008 (IEEE Std 12207-2008), Systems and
software engineering — Software life cycle processes.
2.1 Application of conformance
Throughout this International Standard, “shall” is used to express a provision that is binding, “should” to
express a recommendation among other possibilities, and “may” to indicate a course of action permissible
within the limits of this International Standard.
© ISO/IEC 2012 – All rights reserved
© IEEE 2012 – All rights reserved 1
---------------------- Page: 6 ----------------------
ISO/IEC/IEEE 26515:2012(E)
Use of the nomenclature of this International Standard for the features of agile methodology or the parts of
user documentation (that is, scrum, sprint, chapters, topics, pages, screens, windows, etc.) is not required to
claim conformance.
Conformance to this International Standard may only be claimed by an organization if all of the requirements
in this International Standard can be met by the organization. When conformance is claimed for a multi-
supplier program, it may be the case that no individual supplier may claim conformance because no single
contract calls for all the required activities. Nevertheless, the program, as a whole, may claim conformance if
each of the required activities are performed by an identified party.
This International Standard may be included or referenced in contracts or similar agreements when the parties
(called the acquirer and the supplier) agree that the supplier shall deliver user documentation services in
accordance with this International Standard. It may also be adopted as an in-house standard by a project or
organization that decides to develop documentation in accordance with this International Standard.
Organizations, projects, or multi-supplier programs intending to claim tailored conformance should consult
ISO/IEC 12207/IEEE Std 12207:2008, Annex A, Tailoring Process.
3 Normative references
The following referenced documents are indispensable for the application of this document. For dated
references, only the edition cited applies. For undated references, the latest edition of the referenced
document (including any amendments) applies.
ISO/IEC/IEEE 24765:2010, Systems and software engineering — Vocabulary
4 Terms and definitions
For the purposes of this document, the terms and definitions given in ISO/IEC/IEEE 24765 and the following
apply.
4.1
agile development
software development approach based on iterative development, frequent inspection and adaptation, and
incremental deliveries, in which requirements and solutions evolve through collaboration in cross-functional
teams and through continuous stakeholder feedback
4.2
agile environment
organization or team implementing agile development methods and approaches
4.3
audience
category of users sharing the same or similar characteristics and needs (for example, purpose in using the
documentation, tasks, education level, abilities, training, and experience) that determine the content, structure,
and use of the intended documentation
NOTE There may be a number of different audiences for a software product's documentation (for example,
management, data entry, maintenance).
4.4
burndown chart
document that records project status, usually showing tasks completed against total number of tasks
4.5
documentation
information that explains how to use a software product
NOTE In this International Standard, documentation is used to mean user documentation.
© ISO/IEC 2012 – All rights reserved
2 © IEEE 2012 – All rights reserved
---------------------- Page: 7 ----------------------
ISO/IEC/IEEE 26515:2012(E)
4.6
feature
functional or non-functional distinguishing characteristic of a system, usually an enhancement to an existing
system
4.7
iteration
repetition of a process or activity
4.8
persona
archetypical user of a system, based on research into real users of a system
4.9
scrum
iterative project management framework used in agile development, in which a team agrees on development
items from a requirements backlog and produces them within a short duration of a few weeks
4.10
scrum master
person who facilitates the scrum process within a team or project
4.11
scrum meeting
brief daily project status meeting or other planning meeting in agile development methodologies
NOTE The scrum meeting is usually chaired by the scrum master.
4.12
scrum report
report that documents the daily activities of a scrum team, recording any problems or issues to be dealt with
4.13
scrum team
members of an agile development team working together under the scrum process, usually led by the scrum
master and project owner
4.14
sprint
short time frame, in which a set of software features is developed, leading to a working product that can be
demonstrated to stakeholders
NOTE In some organizations, a sprint is known as an iteration.
4.15
use case
description of the behavioural requirements of a system and its interaction with a user
4.16
user story
simple narrative illustrating the user goals that a software function will satisfy
4.17
writer
person designing or developing user documentation
© ISO/IEC 2012 – All rights reserved
© IEEE 2012 – All rights reserved 3
---------------------- Page: 8 ----------------------
ISO/IEC/IEEE 26515:2012(E)
5 User documentation processes in an agile environment
5.1 Relationship between user and life cycle documentation processes
Teams using agile development shall perform the following activities:
a) identify documents to be produced by the process or project;
b) specify the content and purpose of all documents and plan and schedule their development and
production;
c) identify the standards to be applied for development of documents;
d) develop and publish documents in accordance with identified standards and in accordance with
nominated plans;
e) maintain documents in accordance with specified criteria.
The following information items are used in documentation developed using both traditional and agile
development methods:
description;
plan;
policy;
procedure;
report;
request;
specification.
NOTE 1 ISO/IEC/IEEE 15289:2011 defines the purpose and generic content of these information items.
The software implementation processes are the same between projects using traditional and agile
development methods, but some or all of these stages may be repeated in each sprint. In some projects the
software detailed design process may be shortened or sparsely documented. Code development may
proceed through the development of working prototypes, rather than a detailed specification of the design
being created and approved.
NOTE 2 Annex A contains a brief overview of agile development practices which the information developer may
encounter.
© ISO/IEC 2012 – All rights reserved
4 © IEEE 2012 – All rights reserved
---------------------- Page: 9 ----------------------
ISO/IEC/IEEE 26515:2012(E)
Software Implementation Processes
1. Software Implementation
2. Software Requirements Analysis
3. Software Architectural Design
4. Software Detailed Design
5. Software Construction
6. Software Integration
7. Software Qualification Testing
Figure 1: Software Implementation Process
NOTE 3 ISO/IEC 12207:2008 (IEEE Std 12207-2008), Systems and software engineering — Software life cycle
processes defines the software life cycle processes for a project.
5.2 Life cycle software documentation in an agile environment
Designing, developing, and testing user documentation is greatly assisted by the presence of life-cycle
documentation such as a documentation plan, system design document, system test plan, release records,
and problem reports. Other formal documentation specific to the user documentation development process
may be produced, such as style guides and organizational procedures for content management and
documentation reviews.
ISO/IEC 15289:2011, Systems and software engineering — Content of life cycle information products
(documentation) provides recommended contents for the production of required documents throughout the
systems/software life cycle.
In projects using agile development, any life-cycle documentation that is included in the project is likely to be
less detailed, and possibly less formal than in other types of development projects. Some documents, for
example, detailed specifications and design documents may not be produced at all. Because of the focus on
delivery of working software, not only are some of the documents that traditionally would be produced as a
part of the software life-cycle process not being produced (or are significantly reduced in content), but some of
the processes may be skipped altogether. For example, the development team may proceed straight from
producing a high level architectural design to software coding and testing, skipping the production of a
detailed design.
Communication of the intent and behaviour of the user documentation may instead be provided by face to
face communication, rather than through the use of detailed, formal documentation plans.
The documentation that is produced and the level of detail within each document are likely to be project
specific. The level of detail may be influenced by the size of the team, the location of the team, requirements
of acquirers, and other contractual agreements. More substantial documentation is needed if the team works
in different time-zones or locations. Small, collocated teams may prefer minimal documentation and a reliance
on face to face communication, whereas large, multi-location teams are likely to require more detailed
documentation for communication purposes and future reference.
The types, level of detail, and timing of the production of the documentation will vary between projects. When
the focus is on the delivery of working code, a development team may not have planned to include the
resources needed to produce large quantities of documentation. Mechanisms are still required to ensure that
the software product and associated user documentation match the user requirements; however these may be
defined on the project.
© ISO/IEC 2012 – All rights reserved
© IEEE 2012 – All rights reserved 5
---------------------- Page: 10 ----------------------
ISO/IEC/IEEE 26515:2012(E)
Projects using agile development may benefit from the introduction of alternative content storage systems,
such as wikis, that enable content to be captured quickly and cheaply. These allow information to be rapidly
updated, and to be shared across the development team, including the technical writers, both locally and
across multiple sites and time zones. However, wikis tend to collect chronological information without
structuring the content for usability.
5.3 Life cycle documentation in agile development
Life cycle documentation should be produced in projects using agile development to communicate the
processes, requirements, and deliverables required of the teams working on the project. These documents
may contain less detail than their counterparts in other software development methods. The life cycle
documents produced by projects using agile development are named the same as in other software projects,
but the amount of detail or specific contents may differ.
The life cycle documentation items may not be formal or highly detailed documentation, but they are still
useful in developing the user documentation. These documentation items should be produced by projects
using agile development to assist both the production of software and user documentation that meet
requirements:
project plans;
sprint plans;
requirements documents, (expressed in user stories, scenarios);
high-level design proposals, (may not be needed for agile development);
test plans, (test procedure);
risk statements, (risk register);
user stories;
use cases;
descriptions of personas;
burndown charts;
task lists;
scrum reports;
end of sprint lessons learned reports.
6 Management of information development in an agile environment
6.1 Documentation management considerations for agile development
Agile development is an iterative and incremental approach to software development performed i
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.