Going further than monkeys: Let’s document requirements effectively

In 2011, several popular news portals^[1] published headlines like “Virtual monkeys write Shakespeare”. After reading them, I was pointed to the so-called “Infinite monkey theorem”. It states that “a monkey hitting keys at random on a typewriter keyboard for an infinite amount of time will almost surely type a given text, such as the complete works of William Shakespeare”. After reading this, I confirmed the importance of requirements engineering:

–          We don’t pursue obtaining Shakespeare works, but also something even more complex: information systems that satisfy stakeholder’s needs and expectations. Eliciting, specifying, negotiating and validating the requirements of a system are key challenges since we need having a common definition of our working subject (the system). Analysis and development professionals need to know what they are going to design and build, while maintenance and QA engineers also need to agree on what the system does.

–          In order to achieve this purpose we don’t have “infinite amount of time” and, consequently, we cannot base our work on “hitting keys at random”. We need structured and purpose-based methods.  This is requirements engineering.

Fortunately (at least in software engineering), we go further than monkeys. However, we are people, and everything that involves people implies great challenges. In the context of requirements engineering, agreeing on what the system does is less trivial than somebody expects at first sight. In this context, requirements engineering cannot be based only on the perceptions that each stakeholder has in mind. We need to agree in a common code. But not any language is equally suitable for this purpose and for each role. Requirements specifications are words (or, as we will see, models), but not only words. They are the base of all software activities and they have legal and operational relevance across the whole lifecycle of systems. When explicitly defined, they are an opportunity to address complexity, and a common repository of knowledge that may help perceptions to get closer.

According to a popular quote “if you want to learn something, read about it. If you want to understand something, write about it. If you want to master something, share it”. In order to know about a software system, the same applies, but in order to read, write and share the characteristics of a system, we need an explicit representation of requirements. So, let’s document requirements. But before doing this, we should design a requirements documentation strategy. The reason is clear: if we pursue effective documentation, it needs to be designed in a purpose-based way. Otherwise, it will be only a fashion or, in the other extreme, a big mess, but it will not be useful in terms of enhancing validation, traceability and other quality criteria.

Which aspects need to be considered in such “requirements documentation strategy”?

Quality criteria for the requirements document: Existing criteria (like those included in the IEEE Recommended Practice for Software Requirements Specifications –Standard  830-1998-) formalize quality advices which can be reused as strategic aims to be taken into consideration. The most common criteria applicable to the structure of the entire requirements document are consistency (absence of contradictions between parts of the document), unambiguity (clear specialty of requirements in the whole document and absence of general terms); modificability and extensibility (changes and versioning protocol needs to be defined); completeness (the document needs to specify all relevant requirements);  clear structure (stakeholders require to find what they need in an efficient way); and traceability (the attributes to be recorded for each artifact in order to represent dependencies and sources need to be defined and managed).

Quality criteria for individual requirements specifications: Each particular specification of a requirement also needs to be based on quality criteria. There are several recommendations, but at least they need to be SMART, that is Specific (clear and unambiguous), Measurable (a fit criterion to test the requirement is needed), Achievable (realizable, implementable), Realistic and Time-bounded (a schedule is defined). The task of achieving these quality criteria requires the definition of specification guidelines (which are usually implicitly included in the structure of specialized models and templates) that should be explicitly defined, disseminated and reviewed.

Artifacts, perspectives, methods and supporting tools: For each relevant view of the system (functional, structural, behavioral,…) and each stakeholder perspective, it is needed to select the artifacts to represent such view according to the pursued criteria. The selected artifacts may vary according the purpose of each view, the necessities of stakeholders, the pursued automated verification capabilities and the project context.  Artifacts may adopt the form of natural language descriptions, predefined templates, models, or hybrid combinations of these forms). Many methods and supporting tools suggest artifacts for each considered view of the system.

Responsibilities and management: Stakeholders are the users of requirements documentation. Their skills and project roles should be considered in order to assign documentation responsibilities. In particular, I think that is interesting to include a role responsible for considering the “big picture” of the requirements documentation across the project life activities. This role is essential since traceable and shared requirements specifications need to be managed as central and cross-wise aspects.

The objective of having a requirements documentation strategy is enhancing the requirements engineering value for the success of a project. As requirements play a central role, the way we specify them and the way we manage such specifications have big influence on the project’s result. Therefore, we are challenged to plan, agree and manage requirements specifications by applying a strategy to go further than our dear Shakespeare monkeys.

More information:

[1]http://www.bbc.co.uk/news/technology-15060310, http://edition.cnn.com/2011/09/26/tech/web/monkeys-typewriters-shakespeare/,