ERNI Technology Post Nr. 59: Pragmatic Requirements Documentation

The Agile Manifesto values «working software over comprehensive documentation». While having running software is obviously better than having a perfectly documented yet unimplemented system, the Agile Manifesto does not require having no documentation at all. Thus, the challenge is to document what is required without gold-plating.

Know your audience

We need to know who is using the documentation, as its content differs based on the audience. The style will be different based on whether we are writing for development and testing or quality assurance. In case the domain is governed by a regulating body, the rules of this body must be closely followed. Nevertheless, our experience shows that it is a smooth process to adapt the documentation to these needs.

We start writing the requirements for the people who will first use them: the developers and testers. Every project is different regarding their demands, so you must adapt.

But it is not enough for the developers to understand. By applying techniques such as Domain-Driven Design (DDD), we make sure that a common language is used among all involved stakeholders, so business is able to understand the requirements as well. This also implies avoiding developer jargon in the requirements documentation. Employing this approach, the documentation can even be used to validate your hypotheses concerning requirements with end users.

Artifacts: use whatever helps

A “Gravitational Use Case” acts as the gravity centre for all artifacts. Its description is very lightweight and on a high level. We also use this kind of Use Case in agile environments when working with user stories.

A Use Case by itself is usually not enough to describe the different aspects of requirements. Therefore, we create BPMN diagrams, for example, to show the interconnection between Gravitational Use Cases, or a Business Object Model (BOM), which fosters understanding of how the different business objects are related. Typically, some of these artifacts are reused and enhanced by an architect. By applying lean principles to the documentation, an artifact is created only when it creates added value for the project.


Prototypes are a very powerful tool to validate specifications received from business partners or end users. Using a prototype removes ambiguity and shows basic unspoken user needs. While wireframe mockups provide value for reviewing a textual specification, experience shows that an interactive, clickable prototype is far more powerful; hence, we use it more and more. Its power lies in the ability to evaluate the user experience (UX).

A prototype is a documentation artifact by itself, and is thus connected with Gravitational Use Cases. As stated above, we apply lean principles focusing on value. In case of a prototype, the approach leads to documentation where we only describe what is ambiguous. Time should not be wasted on further description of anything that is obvious through the prototype itself.

Collaboration between documentation and tracking tool

While working on a project, everybody - Business Analysts, Developers and Testers - uses the same tool to track their progress, thus providing transparency. The true power of a tracking tool is unleashed when it is connected with a requirements documentation tool. Then the Gravitational Use Case is connected with the user stories, giving the developers and testers enough information for the current story while providing the whole context within one click.

According to our experience, there is no way around using tools to support requirements and work tracking. With the use of specialised tools, management, change tracking and tracing between Gravitational Use Cases and other artifacts as well as work items is possible with very little effort.


  • Start small and enhance the documentation only when value is added.

  • Lightweight, concise documentation is easy to maintain and is likelier to be used.

  • Tool support is crucial to work with Gravitational Use Cases and to enable transparency.

The approach of using Gravitational Use Cases to keep the documentation together is pragmatic, easy to use and our experience shows that it works.

posted on 16.06.2017
von:Joffrey Zehnder