Requirements Specification (1/5): Why Should You Perform Requirements Documentation?

In requirements engineering (RE), the documentation of requirements and related artifacts plays a central role. However, practitioners often experience challenges in this particular RE activity. This blog post is the first in a five-part series of articles on requirements documentation. In part 1, we explore why requirements are documented at all.

The Role of Documentation in Requirements Engineering

The definition of RE by IREB [1] highlights how the documentation / specification of requirements lies at the heart of RE:

A systematic and disciplined approach to the specification and management of requirements with the following goals:

1. Knowing the relevant requirements, achieving a consensus among the stakeholders about these requirements, documenting them according to given standards, and managing them systematically;
2. Understanding and documenting the stakeholders’ desires and needs;
3. Specifying and managing requirements to minimize the risk of delivering a system that does not meet the stakeholders’ desires and needs.

RE typically comprises the four core activities shown in the figure below, with some sources considering “requirements analysis” a fifth activity, separate from validation and negotiation.

This figure reveals much about the aspects and contribution of documentation within RE from a procedural point of view:

• Documentation is logically the step where the elicited requirements are held in a particular form. Without requirements documentation, a requirement may get lost or be grossly misinterpreted.
• Documentation provides a solid basis for requirements validation and a source for revealing conflicts that need to be resolved through requirements negotiation. Validation requires clearly documented requirements to provide a basis for discussion.
• Documentation is a source for requirements elicitation. Instead of using only survey-based techniques (such as interviews, focus groups, and questionnaires) or observation techniques, many (good) requirements for a system can be obtained from requirements specifications of previous versions and predecessor systems, or through reuse of requirements from other projects.
• Documentation supports requirements management, which focuses on handling requirements over time, in key aspects like planning, prioritization, monitoring, and change management. Without documentation, many aspects of requirements management cannot be performed properly.

The Role of Requirements Documentation in the System Lifecycle

In addition to requirements documentation playing a central role within RE itself, the RE phase is not an end in itself, but focuses on what lies beyond, by providing a base for all subsequent activities within the system lifecycle (cf. [1]). In particular:

• Documented requirements elaborated to the right degree of detail enable more precise estimates for the planning of resources.
• The requirements documentation specifies many of the constraints and key aspects that inform the architectural design of the system.
• The requirements documentation contains the system features that must be implemented and the quality these features must meet.
• Based on the documented requirements, test cases can be derived or even (automatically) generated and the correct system behavior can be specified.
• With proper traceability within the requirements documentation, change management can determine whether a requested change is permissible, and what the impact and costs of a change will be.
• The requirements documentation is a valuable source of information during system usage and system maintenance, and can be a basis for the user manual and for developer documentation.
• The requirements documentation supports contract management in the early stages of a project, throughout the project as changes occur, and during renegotiations.

Key Contributions of Requirements Documentation

Managing complexity: Requirements documentation plays a role in terms of efficiently dealing with content. It is important to understand that a requirements document is not merely a collection of requirements, but that it also involves all the related artifacts. Each requirement can have many different types of artifacts, including those that form the basis for its existence (e.g., interview protocols), products from working with the requirement (e.g., agreement activity reports, change requests), and material created based on requirements (e.g., validation reports, code snippets). Together, these can form vast amounts of information. Moreover, most artifacts relate to several requirements, so these need to be referenced rather than stored together with a single requirement. When the requirements, the relationships between them, and their associated artifacts are structured properly, the documentation allows this complexity to be managed.

Achieving legal compliance: Requirements documents can have a legal impact in two ways. First, in a descriptive sense, a requirements document can specify which laws, regulations, or standards need to be complied with, and include requirements that operationalize the consequences of these legal aspects. This ensures that the system will intrinsically be legally compliant, and the documentation serves as evidence that facilitates the accreditation or review process. Second, in a prescriptive sense, a requirements document can be part of a legally binding contract between the customer specifying the requirements and the party taking on the development of a system. The requirements then serve as the criteria to determine whether the system is built as specified.

Assuring knowledge management: Over extended periods of time, requirements documentation serves as a fallback to the original purposes of the system, a reminder of the intended or envisioned use cases, and a history of the decisions made throughout development [2]. The documentation can be consulted during a (long-standing) project as well as retrospectively after a project has been concluded.

Supporting stakeholder communication: Requirements documentation facilitates communication between stakeholders in several ways. It provides a strong basis for discussions and allows for alignment even in the case of distributed teams. For example, it defines the role of the Product Owner much more clearly for the development team. Documented requirements additionally support a common understanding, especially when they include diagrams or clear language. Stakeholders can also reread the information at a later time to refresh their memory. This becomes especially important when the information is complex.

Facilitating iterative thinking: The documentation of thoughts and ideas supports the person writing them down in their creative process. Writing something down puts this person in a particular mindset that helps them uncover gaps. These notes can also be revisited to make further improvements when new ideas arise. In this case, the documentation is already serving a purpose before a decision is made on whether or not to include it in the requirements documentation, namely that the author was able to explore their knowledge of and ideas for the system.

Introducing and Following a Documentation Process

Only having a structure for the requirements specification in place does not suffice. The motivation of team members to document requirements systematically by following a process that involves guidelines and rules is also required. Without such a process in place, the specification is likely to have many quality defects. A requirements documentation process must fit the organizational structure and culture, but should at least address the following aspects:

Involve stakeholders: Functional requirements and quality requirements are elicited in a structured way through interactions with stakeholders, i.e., all noteworthy persons who can provide requirements, including end-users, team members, and other parties. The documented requirements and any questions about them are again discussed with the stakeholder(s) who provided the requirements in order to uncover and resolve any misunderstandings [3].

Use requirements templates: When we talk about the quality of requirements specifications, we mean aspects such as unambiguity, consistency, clarity of structure, and completeness. Prior to validation, the requirements documentation is the stage where these qualities are either achieved or low quality is produced. Adhering to a standardized structure or template for each type of text-based requirement can greatly contribute to well-written requirements.

Document artifacts: Requirements can serve as a basis through which additional information and artifacts are added in a constructive and pragmatic way. One recommended approach is to gather all artifacts created during the process and attach them to the requirement in order to facilitate knowledge sharing and to have more fine-grained information available that can serve as a basis for discussion. This makes the requirements specification an even better source of information on design decisions and boosts traceability.

Elaborate and plan requirements: An efficient approach to requirements documentation is to systematically refine requirements. This addresses two key aspects of requirements: the fact that they exist at different levels of granularity, and the notion that requirements are subject to change. At each stage, requirements are best elaborated only to the necessary level of abstraction, and through communication: from a project leader, who assures that the goals are approved by the executive board, down to a team leader, who presents the task to the team and discusses questions with developers individually.

Lock requirements for implementation: To assure a clear-cut approach, a clear distinction should be made between requirements that are still fluid and those that are fixed for a particular iteration. Requirements should only be planned for implementation after conceptualization has been completed, and after that, it should be governed by a clear and closely observed change management process. This also protects the development team from being overloaded with unqualified requirements [2].

Establish a glossary: In a development project, a glossary is an important clarification tool. It is a collection of term definitions that can contain aspects such as context-specific technical terms, business terms and jargon, abbreviations and acronyms, everyday terms that have a specific meaning in a particular context, synonyms (different terms with the same meaning, of which only one should be used), and homonyms (similar terms with different meanings) [1].

Perform quality assurance: Quality should be safe-guarded, which includes validating requirements before implementation and performing post-hoc verification of said implementation. Validation assures that the requirements are placed in the correct location, contain the necessary attributes, have been versioned, are written consistently, meet the quality criteria of well-written requirements, and can be tested.

 

references

[1] Rupp, C. & Pohl, K. (2015). Requirements Engineering fundamentals: A study guide for the Certified Professional for Requirements Engineering exam – Foundation Level – IREB compliant (2nd Ed.). San Rafael, CA: Rocky Nook.

[2] Baumann, L., Hruschka, P., Lauenroth, K., Meuten, M., Reis, Rogers, G. et al. (2017). IREB Certified Professional for Requirements Engineering – RE@Agile Primer: Syllabus and Study Guide (Version 1.0.2). Karlsruhe, Germany: International Requirements Engineering Board e.V. Available online: https://www.ireb.org/content/downloads/28-cpre-re-agile-primer-syllabus/ireb_cpre_re%40agileprimersyllabusandstudyguide_en_v1.0.2.pdf (last accessed 11 June 2019).

[3] Schmitt, H., Rost, D., & Weitzel., B. (2015). PQ4Agile AP 2.2 Best Practices: Kundenanforderungen dokumentieren. Sulzbach, Germany: HK Business Solutions GmbH. Projekt „PQ4Agile — Produktqualität für Agile Softwareentwicklung“, BMBF-Förderkennzeichen 01IS13032. Available online: http://www.pqwiki.de/index.php/Kundenanforderungen_dokumentieren (last accessed 11 June 2019).