A common misunderstanding “agile does not need documentation”

Alessandro Stazi, Andrea Gocke and Sissi Closs

In December 2018, the International Organization for Standardization (ISO) published a new version of the standard: ISO/IEC/IEEE 26515:2018 Systems and software engineering − Developing information for users in an agile environment. Not only the title of the standard was changed. Read more about the scope of the second edition and how it can help you in your daily work.

WHY “INFORMATION FOR USERS” AND NOT “DOCUMENTATION”?

Earlier versions of the 2651x standards followed the classic perspective of book-oriented documentation which sees the results of the information development process as a single book or multivolume set. But increasingly, information for users is now produced from a pool of re-usable topics and presented in a variety of media. This includes information available on the user interface, such as UI texts (e.g. field labels, messages), embedded help (e.g. mouseover, longer onscreen explanations), and multimedia systems using animation, video, and sound as well as printed documentation. Therefore, the new versions of the 2651x standards use the more convenient umbrella term “information for users”.

WHAT IS AGILE DEVELOPMENT?

Today, many companies worldwide use agile processes to develop their products. Agile development is not a single process or set of defined methodologies, but rather, a set of principles and related methodologies based on principles described in the Manifesto for Agile Software Development (published in 2001). Key features of these agile development methodologies are iterative development and the evolution of requirements and solutions over time through the collaboration between self-organizing cross-functional teams. The goal of each iteration is to produce shippable features ready to be used by the customer. To improve things (e.g. results, collaboration, planning) for the next iteration, each iteration ends with a retrospective including customer feedback.

A COMMON MISUNDERSTANDING “AGILE DOES NOT NEED DOCUMENTATION”

The new version of the standard takes up this misunderstanding and sets things right based on a clear distinction between:

• The internal documentation (e.g. specifications) associated with the product development process
• The information for users which is provided together with the produc

In the classic waterfall processes, a lot of internal documentation is created to define and track all steps of the development process. Agile development methods however, rely on the individual teams to decide how to develop and deliver a product that satisfies the requirements. Involvement from requirements to delivery encourages all team members to have the same knowledge and understanding about the user requirements and how they will be fulfilled. Because the team works together and has the same knowledge of the what, why, and how, there is less immediate need to produce and understand detailed specifications for both the project life cycle and the tracking project status. Thus, the internal documentation in the traditional sense is considerably reduced and appears in other forms, such as user stories or backlog items. Information that is specifically targeted at the users, however, is still required and needs to be well-designed and written clearly.

MAIN AREAS COVERED BY THE STANDARD

Chapter 5: Information development process  

Chapter 5 covers the overall requirements for information in the product life cycle. Agile development methods discourage the creation of detailed engineering support documentation and technical specifications. So information developers have to find other, more direct ways of learning about the features to be developed. And time is short, an iteration is roughly 2-4 weeks. The most successful option is to become a (true) member of the development team. Chapter 5 lists the agile practices which affect the information development process.

Chapter 6: Management of information development

Chapter 6 covers requirements for the information development lead or project manager to plan an agile information development project and manage the information development activities in an agile environment. The main topics are:  

• Tasks and roles in an agile development team focusing on the information developer
• Communication challenges, in particular:
  • A small, co-located development team in which the information developer works closely with the development team
  • A globally distributed development team in which two or more groups (of the same company or different software companies) work together to develop different parts of a software package

• Ensuring common standards (tools, style guides, delivery formats etc.) that are used by the different teams that work on different features of the product
• Dynamic staffing of information developers in the different iterations, as appropriate for the priorities in each iteration
• Monitoring progress of information development activities and managing last minute changes

Chapter 7: Preparing information for users 

Chapter 7 covers requirements for designing, developing, and providing information for users in an agile environment. Key aspects in an agile environment are:

• The product and the associated information for users are planned, designed, developed, tested, distributed, and maintained together. 
• The information developer role gets more importance in the entire product life cycle.

Annex A

There are different agile development frameworks (for example, SCRUM) that promote development iterations, teamwork, collaboration, and process adaptability throughout the life cycle of the project. Annex A lists the main methods for implementing agile processes.

WHO NEEDS THIS STANDARD?

This standard outlines not only the most advanced best practices for creating information for users in agile environment. It also promotes a more central role of information developers in the product value chain.
This standard is useful for: 

• Organizations that are adopting agile processes
• Integrating information developers in an agile team
• Improving the collaboration between information developers in different agile teams that work on different parts of the same product
• Improving the efficiency and reducing costs for the producing information for users