English | EN Going further than monkeys: Let’s document requirements effectively
Apr 25, 2014
Several popular news portals published in 2011 headlines like “Virtual monkeys write Shakespeare” that pointed to the so-called Infinite monkey theorem: “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”. It suggests that by working without previously defined methods aimed at overcoming time and resource limitations we could also reach, by chance and spending indeterminate time, the demanded requirements. The importance of requirements engineering is clearly related to this theorem. First, because we don’t pursue obtaining Shakespeare works, but something even more complex: information systems aligned with stakeholder’s needs and expectations (requirements). Second, because in contrast with the monkey theorem, software professionals 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). These observations drive us to requirements engineering.
Fortunately, we work to go further than the monkeys of the theorem by establishing a requirements engineering approach in order to addresses the challenge of agreeing on what the system does or needs to do (a question that is less trivial than somebody expects at first sight). Requirements (desired characteristics of a system) always exist, but not always are explicitly documented to facilitate its validation and traceability across the project life. In this context, performing requirements management based only on the perceptions that each stakeholder has in mind is a common cause of rework, requirements conflicts, etc. Therefore, we need to perform central management of requirements by agreeing in a common and explicit code (a set of artifacts to specify such requirements) to communicate such requirements. Even in agile contexts, requirements validation is essential, and a quality gate to perform such validation and agreement for each iteration (bigger or smaller) is needed to make solid progress based on (more or less) continuous explicit requirements specification checks.
So, let’s document requirements based on a prior design of a purpose-based requirements documentation strategy that should include the aspects explained below.
Existing criteria (like those included in the IEEE Standard 830-1998-) formalize quality aspects which can be reused and applied as checklists and specification guidelines when documenting requirements. We need to establish our criteria in the requirements documentation strategy. The most common criteria applicable to the structure of the entire requirements document are consistency (absence of contradictions that usually evolve to conflicts), unambiguity (clear specialty of requirements); modificability and extensibility (changing and versioning protocols to avoid non up-to-date documentation that devaluates its value); completeness (all relevant requirements need to be specified); clear structure (stakeholders require to find what they need in an efficient way); and traceability (we need to determine the attributes to be recorded for each requirement artifact in order to represent dependent, source and realization artifacts).
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).
For each relevant view of the system (functional, structural, behavioral,…) and each stakeholder perspective, it is also required to determine the artifacts chosen to represent such view. The selected artifacts adopt different forms according to the purpose of the view, and different levels of formalism according to the desired level of verification capabilities. Artifacts may be natural language descriptions, predefined templates, models, or hybrid combinations of these forms.
Finally, it is crucial to consider stakeholders as the users of requirements. Their skills and project roles should be considered in order to assign documentation responsibilities. In particular, it is really interesting to include a role responsible for taking into account the “big picture” of the requirements documentation across the project life activities, 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 documentation strategy to go further than our dear Shakespeare monkeys.
About the author
