Skip to main content

Why Can’t John Write Requirements?

whycantjohn4The purpose of this article is to provide business analysts with further insight into why writing requirements must be a conscious effort of using an elaborative language. This elaborate language provides details through the use of specifics and metrics, where possible. Because business analysts work inside business area bubbles, it is their nature to write in a restrictive language that assumes everyone understands the nuances of their words. They naturally speak in a condensed code and therefore write requirements in the same condensed format. As a result, they unconsciously imply additional meanings to their words. Unfortunately when their documents are handed-off to systems analysts, who just happen to live in a different bubble, the requirements are misinterpreted.

Studies [1] have shown that the majority of software defects found in testing can be traced back to inadequate requirements definition. Much has been said on how to ensure the quality of the final deliverable of the analysis phase – the business requirements document (BRD). The BRD is the major document produced by business analysts when employing a “waterfall” System Development Life Cycle (SDLC). Professional technical writers cite the three qualities for documents: clear, complete, and concise. To achieve the three Cs, business analysts utilized quality assurance techniques in the form of desk checking, walk-through, peer review, and inspections on the BRD, depending on the risk associated with the requirements.

Of course, one might say that the root cause of the BRD quality struggle is the SDLC chosen. In an agile SDLC, the BRD hand-off from the business analyst to the system analyst simply does not exist. Instead, agile teams develop requirements via direct customer-developer conversations using user stories. However, misinterpretations are not limited to the written word. User story conversations during agile development can lead to just as much misunderstanding perhaps even more, since speech is typically even more casual.

Restrictive and Elaborative Languages

Recently I came across a 1970s study [2] by a British sociologist, Basil Bernstein, on language codes that provide some insight. His premise was that depending on the social class of children in school they tended to use one of two language codes: one was restricted, the other was elaborate. The restrictive language is a condensed form of communication. It carries a social message of inclusion. Essentially, the restrictive language assumes that the receiver has a common understanding, either through shared experiences or background. It reminds me of the ubiquitous phrase of “you know what I mean” that we hear in conversations. In contrast, elaborative language is not condensed. It is very detailed and does not assume the receiver has a common understanding. In fact, it assumes just the opposite. Specifics are provided to make the message clear, complete, and concise.

A Simple Example

A simple, but meaningful example for everyone, is the typical hygiene sign one sees inside a restroom. See the example below: the one on the left uses restrictive code and the one on the right uses elaborative code.

whycantjohn1

Figure 1. Example of Restrictive and Elaborative Code

The restrictive coded sign leaves much to interpret such as use of soap, water temperature, and wash duration. I have noted in the past five years that the elaborative coded sign is being used more often.

The Bubble Principle

We all live in our own worlds commonly known as bubbles. These bubbles are the business domains. We share this world with others and naturally develop a restrictive language within it. This restrictive language consists of codes that contain implied messages in the form of business words, phrases, and of course acronyms. We conduct interviews and meetings using this condensed form of communication. In writing and validating requirements, we interface with stakeholders in our bubble. We can apply the elaborate language in our struggle to ensure quality in a business requirements document. Unfortunately, we have a natural and unconscious tendency to use our restrictive language – “you know what I mean”.

whycantjohn2
Figure 2. Business Area Bubbles

In order to overcome our struggle, we must consciously utilize an elaborative language in writing requirements. Spelling out all detail in requirements ensures the receivers can understand them without misinterpretation. This also solves the problem of determining if a requirement is achieved in development – testability. Elaborative requirements provide enough specifics to allow proof that the requirement is met.

Requirements Examples

Below are some restrictive and elaborative language examples. The restrictive message is condensed and, depending on the reader’s familiarity with the business area, carries an implicit message. In comparison, the elaborative message is detailed leaving less room for misinterpretation. Note the use of details and metrics in the elaborative language in the requirements examples below.

Restrictive Elaborative
The system must be backed-up on a regular basis. The system must be backed-up at midnight every Saturday. Two back-up copies need to be taken; one stored on-site and one off-site.
The system must allow users to view expense accounts. The system shall allow users to view only their own expense account for the past six months.
The system must be available during business hours. The system must be available to users 95% of the time during the hours of 8 AM to 6 PM central time Mon. thru Fri.
The system must provide users a weekly sales report on Fridays. The system must provide sales managers a weekly sales report by 9 AM central time on Friday. The sales report is defined in section……….

Table 1. Comparison of Restrictive and Elaborate Languages

Conscious Effort

Elaborative language does not happen naturally. The BA must make a conscious effort in making requirements understandable by people outside the business area bubble by adding detail – specifics and metrics, where possible. I recommend that one of the quality assurance reviews focus on elaborate language.

whycantjohn3

The intent of this article is to provide the business analyst further insight into why writing requirements must be a conscious effort of using elaborative language. Note that elaborative language is just as vital in conversations (e.g., user story conversations during agile development iterations). The bubble principle still applies regardless of the SDLC used.

About the Title

I derived the title from the classic 1986 book on phonetics [3], “Why can’t Johnny read?” I decided to use the name John – now a grown-up business analyst. However, since the struggle is with both the written and spoken word, perhaps I should have expanded the title to “Why can John neither write nor discuss requirements?” You know what I mean…………….

Don’t forget to leave your comments below


Mark Monteleone holds a B.S. in physics and an M.S. in computing science from Texas A&M University. He is certified as a Project Management Professional (PMP®) by the Project Management Institute (PMI®), a Certified Business Analysis Professional (CBAP®) by the International Institute of Business Analysis (IIBA®), a Certified ScrumMaster (CSMTM) and Certified Scrum Product Owner (CSPOTM) by the Scrum Alliance. He holds an Advanced Master’s Certificate in Project Management and a Business Analyst Certification (CBA®) from George Washington University School of Business. Mark is also a member of the Association for the Advancement of Cost Engineering (AACE) and the International Association of Facilitators (IAF). Mark is the President of Monteleone Consulting, LLC and can be contacted via e-mail – [email protected].

References

1 Johnson, Jim (2006) My Life is Failure; Standish Group International
2 Bernstein, Basil (1971) Class, Codes and Control vol 1 London; Paladin
3 Flesch, Rudolf Franz (1986) Why can’t Johnny read: and what you can do about it; Harper Paperbacks