Going further than monkeys: Let’s document requirements effectively

monkeys_shakespeareSeveral 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.

Albert Tort


Albert Tort is CTO of Sogeti Spain. He is a software engineering and testing & quality assurance specialist.

More on Albert Tort.

Related Posts

Your email address will not be published. Required fields are marked *

4 + 4 =

  1. prasanna ram April 28, 2014 Reply

    speaking about the need to documenting requirements has been beaten to death by now. i see articles speaking about this time and again. given that why is the other side of the story not given much focus.

    the question on the other side is simple “why some projects do not follow a diligent requirements phase and documentation”

    • jos punter May 2, 2014 Reply

      I think you got a point about a dilligent requirement and documentation. But why a phase ? By creating a phase you setup a “trap” for creating a big design up front.

      • Albert Tort May 5, 2014 Reply

        I agree. In fact, I don’t propose to document requirements in a specific phase of a project. Regardless the project methodology, requirements always exists, although many times are not documented based on a strategy and are only in the mind of each stakeholder (each one with particular perceptions and expectations about a system). Although requirements engineering is usually conceived as a preliminary phase, requirements exists throughout a project (many artifacts, including implementation or QA artifacts need to be linked with requirements specifications and evolve/realize/assure them).

        The point is trying to document requirements according to a strategy that avoids documenting with the purpose of making documentation useful for all the activities in a project that need to manage requirements (most of the activities, from development to QA have this necessity). In order to do this, you need to design, first, a documentation strategy, otherwise it is probably that the documentation will not be very useful nor aligned with the “big picture” of the project.

    • Albert Tort May 5, 2014 Reply

      I think that this is a matter of project organization for investing in avoiding costly problems as soon as possible (PointZero -http://www.sogeti.com/pointzero- is about that and clearly states that as later problems are faced, more costly they are) or cutting costs of project knowledge management and “we will see”. The main problem is that many documentation does not rely on purpose-based documentation strategies to make it “fit for purpose”. In such cases, documentation (if exists) of requirements is, obviously, not useful and very costly, and therefore it is not valuable. A key aspect of project success is how we manage requirements and its impact, and it necessarily needs to rely on a strategy in advance.

  2. Jos Punter April 28, 2014 Reply

    If i understand it correctly you should start document effectivly first and when that’s done you are able to start developing ?

    • Albert Tort May 5, 2014 Reply

      The idea is not only documenting effectively first, but also as soon as possible, and ensure traceability of such requirements specification throughout the project. For example, if a suitable requirements documentation strategy is previously designed and applied, then we can early detect requirements inconsistencies. If this inconsistencies are not resolved early with the assistance of effective documentation, then a conflict will probably appear later (its resolution cost will be higher).