This is part 4 of the blog series “Communicating Requirements – Effectively”.

In part 3, I introduced the basic communications model from a requirements perspective.

In this part 4, I discuss the advantages of text-based requirements vs alternate forms of communicating requirements.

———————

Advantages of Text-based Requirements vs. Alternate Forms of Communicating Requirements

For some of the sources listed in Figure 1 in the previous post, diagrams and models may be the best means of communications; communicating a thought or idea much more succinctly than can be done with text-based requirements, especially when the thought or idea is very complex.  However, for many of the other sources, text-based requirements are the most effective form of communication.

An argument that is frequently used against the use of text-based requirements is that written language is always going to be ambiguous and that diagrams and models more clearly communicate the intent.  Another key argument is that “a picture is worth a thousand words”. With these perspectives, there are some who are adopting MBSE and Agile methodologies that believe, arguably, text-based requirements are not useful and not needed.   However, there are several issues that need to be addressed from this perspective.

* Use cases and user stories are written in terms of the user’s (actor’s) interaction with other actors and use cases within the system under development rather in terms of what the system under development needs to do in order for the users to interact in the way they expect to, as defined by the use cases. While use cases are an excellent tool for stakeholder expectation analysis to help understand the features and associated functionality and performance of the system of interest expected by the stakeholders, they do not always effectively replace well-formed, text-based requirement statements for all the various ideas and concepts that must be communicated, especially non-functional requirements.

* Proponents of text-based requirement statements may ask: “If the developer cannot translate the needs uncovered during their use case analysis into properly written text-based requirement statements, do they really understand what is needed? If they can’t clearly communicate was is needed, how do they expect anyone else to?”  From an Agile perspective, translating into text-based requirement statements often adds ambiguity. In addition, often the set of text-based requirements are incorrect, inconsistent, and incomplete. Stakeholders frequently don’t’ really know what they want or need at the beginning, resulting in continuous change.  Why not translate the stakeholder needs, as communicated informally, directly into a design and workable software/hardware that adds value – like the old saying “The proof is in the pudding!” Using timely feedback from the stakeholders, the design and code can be quickly updated to meet the needs of the stakeholders and add value to the organization.  Without the burden (time and effort) that comes with formal means of communicating requirements and changes, Agile is able to deliver value to the customer faster and with less effort.

* Use cases, diagrams, and other model forms do not yet cover the wide range of ideas and concepts needed such that, as requirements, they do not have the characteristics of well-formed requirement statements and sets of requirements that are necessary to clearly communicate the broad spectrum of stakeholder needs into a language that can be clearly understood by the developers, testers, and other stakeholders over time. Use cases, diagrams, and other model forms and are not always the best form for communicating all the various ideas and concepts that need to be communicated via requirements.

For many ideas and concepts that need to be communicated, well-formed, text-based requirement statements have been proven to the most effective.  Advantages of well-formed text-based requirements include:

* Communication: There is still (arguably, there will always be) a very sizeable audience who cannot interpret, do not understand, or who are not willing to work with, diagrammatic representations of requirements, especially when the words (technical jargon) used are not intuitive to the receiver. These people, particularly the users of the system, may not have been trained in language-based models or find the terminology used in some models to not be intuitive. When this is the case, effective communication has not taken place since the receiver of the message may not interpret and understand the message as intended by the sender and may well lose interest in the requirements elicitation activity.  On the other hand, text is universal.  Of course, the text-based requirement statements have to be well-written in such a way as to be clear, correct, and unambiguous; but then diagrams can also be unclear, incorrect, and ambiguous if they are poorly formed, defective, or the wrong meaning is assigned to them.

* Power of expression. There is no limitation on the types of requirements that need to be expressed. User stories, scenarios, diagrams, models, and use cases, tend to focus on the functional architecture and may be capable of expressing functional, performance, and interface requirements but are not presently well suited to expressing non-functional requirements dealing with the physical architectural elements associated with quality (-ilities), regulations, standards, and physical characteristics. Textual requirements carry the universal power of expression of natural language for all types of requirements.  From an Agile and MBSE perspective, the non-functional types of requirements listed often are classified using the broad category of business rules, business requirements, success, evaluation, and acceptance criteria – which are often communicated as text; with or without a “shall”. From the traditional, text-based “shall” requirement perspective, the Agile development team may deliver a “working product” that meets the customer “explicitly stated” needs and user acceptance criteria, but may not meet essential implicit quality (“-ility”) requirements and requirements in standards or regulations that were not stated explicitly by the customer and not addressed in the use cases, diagrams, and models.  From an Agile and MBSE perspective, this statement is not true—Agile and MBSE development methodologies will uncover the essential, non-functional implicit requirements, as well as is done using the traditional SE methodologies.

* Accessibility: Even if stakeholders are willing to spend the time to learn modelling languages (UML, SysML, etc.), the SE tools (including requirement management tools) and modeling languages used to create and view the data and information represented by the model’s dataset are not as available and assessable to all stakeholders. In many cases access is restricted by the number of “seats” or “licenses” purchased.  Being able to provide requirements in an electronic document format (pdf, or common office application formats) allows the stakeholders to view the requirements in applications most will have installed on their personal computers.  In addition, there are still managers from the old-school who still prefer, and demand, printed, text-based documents.  From an Agile and MBSE perspective, requirements, no matter the form, can be communicated via standard office applications that are accessible to all.

* Attributes:  Earlier we defined a requirement expression to include both the requirement statement plus a set of attributes.  Another advantage of a text-based requirement expressions is that the requirement expression can contain attributes (as we define them in this paper) that can be used to manage the requirements.  While modeling languages allow users to define an entity having the name “attribute” and link that entity to a requirement statement, few practitioners do so.  User stories, use case diagrams, and other diagrams to represent a requirement statement are generally not conducive to appending a set of attributes in the way we define them.

* Binding Agreement. Text-based requirement “shall” statements are more easily understood in an agreement or contract based system development effort by a wider, and often, non-technical set of stakeholders. Use of “shall” or other term defined to have the same meaning, makes it clear that what is being communicated is formal and that the statement is a binding and will be verified.  When a list of text statements is provided that do not contain a word like “shall”, it is not clear whether the statement is a binding requirement, a goal, a statement of fact, a wish, or a desire.  Using a set of text-based “shall” requirement statements makes it clear that the statement represents a binding agreement between the requirement owner and the developers that will be verified as part of the acceptance process.  To be part of a binding agreement, especially in a legal contract, the requirements must be expressed in a form that 1) makes it clear the statement is a binding requirement and 2) has the characteristics of well-formed requirement statements and sets of requirements. A complete list of characteristics for well-formed requirement statements and sets of requirements is included in part 5 of this blog series.  Currently, no other form, other than textual “shall” requirement statements, has shown to meet these characteristics.

* System Verification. Most formal agreement (contract) based product development processes include system verification as a formal process that must occur prior to system acceptance. System verification is defined as the process of providing distinctive evidence that the designed and built system of interest meets the requirements that drove design, coding, and manufacturing activities.  Thus, a key characteristic of all well-formed requirements is that they are clear, unambiguous, correct, feasible, and verifiable. From an Agile perspective, the defined and agreed-to success, acceptance, and evaluation criteria, no matter the form, represents the stakeholder needs.  Rather than wasting time on proving the system of interest meets a set of requirements (system verification) that is often ambiguous, incomplete, incorrect, and inconsistent, it is more important to show the system meets the stakeholder needs (system validation). Note that this view is not universally accepted by everyone in the software development community.  The IIBA Business Analyst Book of Knowledge (BABOK) makes a clear distinction between system verification (meeting requirements) and system validation (meeting stakeholder needs in the operational environment.)

———————

In part 5 of this blog series, I conclude the series with a discussion on the characteristics of well-formed requirement statements, sets of requirements, and attributes.

Comments are welcome.

If you have any other topics you would like addressed in our blog, feel free to let us know via our “Ask the Experts” page and we will do our best to provide a timely response.