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

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

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.

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.

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 (CSM^TM) and Certified Scrum Product Owner (CSPO^TM) 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 - mark.a.monteleone@sbcglobal.net.

References

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

Comments (27)

Subscribe to this comment's feed

...
written by Holly Martin, May 11, 2010

Good one, especially like the examples.

• 
• +1
• 
• 

...
written by Arun Prasad, May 11, 2010

Nice one and indeed , elaborate languages play a major role in writing a BRD document.
Thanks for the explanation...

• 
• +0
• 
• 

...
written by Mark Parker, May 11, 2010

Very good article. Another point that could be made is that BAs should make a conscious effort of extracting more elaborative requirements from Business Owners. Too often people are "vague" when giving requirements, because they don't want to be accountable for giving wrong information. It is our responsibility to not only notice these vague gaps, but to also rectify them.

• 
• +7
• 
• 

...
written by Countman Knight, May 11, 2010

Good article. Occasional confusion between elaborate and elaborative, which do not mean the same.

I would just like to point out that in your examples, the elaborative requirements are actually lower-level requirements of the restrictive ones. For instance, on the very first line, the restrictive requirement states a business requirement. The first sentence of the elaborative requirement is a frequency requirement + a timing requirement. The second sentence of the elaborative requirement is a level of protection requirement. If you are going to that level, you may also want to specify number of generations of backups that should be kept.

In general, requirements are hierarchical, and you can drill down until you hit something that cannot be broken down finer. This has nothing to do with communication style, but is intrinsic to the nature of requirements. How far down you need to drill is strongly dependent on whether there are other processes in your organization that can fill in the remaining detail - e.g., there may be backup standards to which the business requirement may map.

• 
• +11
• 
• 

...
written by Richard Boulter, May 11, 2010

Some very valid points made about language style and Countman's point about the hierarchy of requirements. Both point to that essential role for the BA of being able to walk the walk in different arenas. In my experience the BA can typically talk to one area and write for another. This of course leads to all sorts of problems.

The simple solution is to ensure that when the initial requirements are written down they are played back to the originators in a style that best suits them in a setting that makes sense to them. There is the useful phrase to remember in communication: say it seven times in seven different ways. Do not take a front line user and stick them in a room and walk them through requirements line by line. Take the time to invigorate your style to suit the audience.

The language used in writing is only part of the battle to be won - work on the communication and presentation style.

• 
• +4
• 
• 

...
written by John Collins, May 11, 2010

Excellent article. The point to be made is all participants in the requirement process/development should adhere to elaborative language.

• 
• -1
• 
• 

...
written by Des Kenny, May 11, 2010

Valid points.

BTW , :-) , In your second example you changed the verb qualifier from "must" to "shall". No doubt a slip of elaboration.

To elaborate: "The system must allow users..." changed to "The system shall allow users ..."

This is more than elaboration it is a transformation of stakeholder intent since "must" is a stronger intent than "shall".

I agree that you should extract as much detail as possible from stakeholders. However, the level of detail depends on the level of the person in the organisational hierarchy and their level of functional specialisation.

To elaborate: if you are interviewing senior managment they will not know about the details of how or when or where backups are performed. They only want to know that they are done reliably as required by a Service Level Agreement.

In summary: What requirements elaboration you get depends on who you ask as well as how you ask questions.

• 
• +0
• 
• 

...
written by Lucia Dupard, May 11, 2010

This is an excellent, excellent (did I say excellent?) article! The examples are clear and relevant.

• 
• -1
• 
• 

...
written by Simon Papson, May 11, 2010

I've sometimes been accused of being a bit too wordy whenever I document requirements. Now I see why I do it: I've been naturally using a style similar to the one which you've described here as "elaborative", and it often takes more words to describe something more accurately and clearly. I also spell out acronyms when I first use them, and define all business terms.

However, I strongly believe that specific facts & figures ("95% of users", "Monday to Friday") are usually best left out of any primary documentation, and listed separately (appendices are great for this!). This makes sure that users and the business can focus on the main functions, without getting distracted by details (Should it be 95% or 98%? Is close of business at 6pm or 7pm? etc...).

On the "must" vs "shall" issue which has been touched on here - I avoid this entirely by using "will". If the business wants something done by the system, then the system will do it. As simple as that. No implied orders ("it must do this") or declarations ("it shall allow this"), just a simple statement of fact: "the system will display a user's own expense account history to the user". Or, my preferred option: "a user will see their own expense account history".

• 
• +4
• 
• 

...
written by Aruna, May 12, 2010

As a business analsyt, I do agree that the requirements must be elaborative but we need to understand that there is a very thin line between 'being elaborative' and 'being verbose'. In our enthusiasm to capture requirements to the last tee, we may end up being extremely detailed. In this situation the business users may find the additional infomation more of an 'FYI' rather than any value-add.

Hence, the trick is to strike the right balance which one acquires by experience and over a period of time.As someone has rightly mentioned, the level of detailing also depends on the target audience. So, one has to keep that in mind as well.

• 
• +1
• 
• 

...
written by Shakkya, May 12, 2010

Good one !!!

• 
• +0
• 
• 

...
written by Yvette, May 12, 2010

Very good, resembling the three c's clear, complete and consise.

• 
• +0
• 
• 

...
written by Yakita, May 12, 2010

As a business analyst, I feel, the more elaborate the requirements are, the more complete they can be called as......

• 
• +3
• 
• 

...
written by Suhas Gujarathi, May 12, 2010

Great article - Notes:
BAs must be elaborative
BAs must wait to get to a certain point in the project to be elaborative
BAs must understand their teams to decide how elaborative they need to be

• 
• +1
• 
• 

...
written by Graham Worsley, May 12, 2010

Good article.
Requirements document always have at least 2 audiences. The stakeholders providing the requiremts and the next group of specialists in the development production line (e.g. Systems Analysts, Designers). So what is a perfectly clear requirement to one audience can result in many questions from the second audience. Always write requirements for the less domain aware audience.

Also don't forget the power of a glossary.

So the next challenge is we have elaborative requirements, a glossary and 5 minutes to get them signed-off.

• 
• +0
• 
• 

...
written by msthorley, May 12, 2010

I can't be believe so many BAs think this is a good article! I beg to differ. Firstly, the examples given do not merely "elaborate" more "restrictive" versions of the same requirements, they are, in fact, entirely different requirements. Secondly, who writes BRDs? Where've you guys been? We write use cases, produce data models, class diagrams, process models and use a hundred other STUCTURED and more RIGOROUS techniques to avoid the ambiguities of the English language. The answer isn't to write more elaborate English! The answer is to use proven business analysis techniques! Much of the elaboration of the examples doesn't actually make the requirement clear, it's purpose is to provide context and that is exactly what artifacts such as use cases do except without the inherent repetition which would result from this approach.

I'm not arguing against clarity of [removed]although even then I would sound a caution about the need to be concise) but I AM arguing against lists of free-format lengthy written requirements ever being a good way to document detailed requirements!

• 
• +0
• 
• 

...
written by msthorley, May 12, 2010

See also the following recent article: http://www.batimes.com/article...s-why.html for why more elaborate requirements is not the answer!

• 
• +0
• 
• 

...
written by Mark Parker, May 12, 2010

To guest: In your eager attempt to discredit the reader I believe you missed the whole purpose of the article. Hence, that's probably why you simply commented as "guest". It really does depend on your company's SDLC process.

I would assume the author's SDLC structure is very similar to my own. In our "waterfall" approach, the BAs write a BRD/FRD document that captures Business and Functional Requirements from a Business Owner's standpoint. This document is then further dissected in an SRD that contains UCs, data models, class diagrams, UIs etc to be used by analysts and developers. When the Quality Assurance team writes test cases they usually do it from the BRD/FRD standpoint as their sole purpose is to ensure that the Business Owners' requirements were met. Unfortunately the SRD section is an afterthought to them many times.

Sure, vague and restrictive requirements allow for more flexibility if you're trying to CYA or are working with people that understand all the ins and outs of the system, but in the long run can result in more headaches for the BA in explaining that the process doesn't just stop after the BRD/FRD.

It truly is a fine line between being elaborative and just being verbose. The truth of the matter is that this process as a whole isn't the greatest, but it has been around the longest. Old habits die hard they say. The article by msthorley makes this point even clearer. As more and more companies progress into a more Agile or hybrid form of their SDLC, I believe you will see less and less of the problems the author of this article was attempting to address.

• 
• -1
• 
• 

...
written by Dawn Volesky, May 12, 2010

I agree with "guest" to a great degree. Creating the requirements in detailed text often is a huge effort that is rewarded with little to no consumption of the amount of detail by the systems analysts. The nature of a graphically oriented generation of designers and developers is anti-text. Better to use models, diagrams mock-ups and other tools to get your point across. As for keeping the details in yet another place.... More maintenance headaches and mis-communication ensues while putting the pieces of the puzzle together.

That said, detail IS important and can mean the difference between failure and success. The challenge is to build the right kind of documents for the roles that will use them to accomplish the work. Build the requirements in the "language" that works for them, not the BA's only.

• 
• +1
• 
• 

...
written by Christine Roque, May 12, 2010

I agree with comments made in a few of the previous posts - the key is to find the right level of detail to include, as well as ensuring that we are writing for the intended audience of the document.

• 
• +1
• 
• 

...
written by leslie munday, May 12, 2010

Glossary; Yes!

Quantifiable requirements - yes! IMO: Requirements must be testable, else they are not requirements they are a description of a want.
(continued ..}

• 
• +0
• 
• 

...
written by leslie munday, May 12, 2010

Being elaborative, is about using a language that is testable. To quote the above examples:

- The system must be backed-up on a regular basis. [The word 'regular' has no explicit meaning - it is not testable.]
- 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. ['at midnight', 'off-site' and 'on-site' need clarification. ]
- The system must allow users to view expense accounts. [The word 'allow' is always open to interpretation in any context. ]
- The system shall allow users to view only their own expense account for the past six months. [The word 'only' is redundant. Take it out and does the requirement change - IMO, no! This is an example of where being too over elaborative can confuse the reader. does only mean 'no-one elses expense account?', 'or 'they are not allowed to do anything else', which implies the system must paralyze them once they have displayed their account data.]
- The system must be available during business hours. [The words 'available' (- does this mean full or limited capabiltiy?), and 'business hours' need definition.]
- 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. [Assuming that 'available' means 'fully-operational', then this appears to be complete. Going to be a bugger to test though.]
- The system must provide users a weekly sales report on Fridays. ['weekly sales report' has been defined in the glossary. The requirement also implies that the report is not needed before Saturday.]
- The system must provide sales managers a weekly sales report by 9 AM central time on Friday. The sales report is defined in section [Yes.]

Did I mention that I enjoyed the article! I do not see enough discussion on Glossaries. So I will post one that I wrote recently.

Leslie.

• 
• +2
• 
• 

...
written by Shelley Ruth, May 12, 2010

Yikes - the bitter pill! Reading this is as bad as my son calling me on something I did wrong.....

• 
• +0
• 
• 

...
written by Steven A Jones, May 13, 2010

I enjoyed the article. One other thing to say about elaborative style, in addition to being testable, is also a form of CYA. I am often told I am "too wordy" or "there's too much detail". IMO, if I hand a document to business person, systems person, QA, and independent 3rd party, there should be enough detail contained within the documents (business or functional) that there isn't much need for clarifying questions. If there's a lot of questions, I feel I haven't done my job well enough regarding communication of requirements.,, with the 3rd party being my true control for understanding.

I did find it amusing that most of the article was about the BRD but the requirements examples were functionals - much like the typical ATM scenario which usually talks about the functional requirements and not the business requirements.

Steve

• 
• +0
• 
• 

...
written by a guest, May 24, 2010

I see this situation with getting restrictive requirements most often when the Business Champions are delegated to produce the requirements in the form of the traditional BRD. Although highly knowledgeable about the business they are given the responsibility of providing requirements without the fundamental business analyst skills and techniques needed to write (elaborate) the basic clear, concise and complete requirements.

Granted, the traditional BRD is a high level list of the needs of the business. What projects often don't realize (and don't put in the project plan) is that those business requirements need to be decomposed into the more detailed (elaborated) functional specifications (using an experienced BA). Given that, the BRD inadvertantly becomes "the" requirements and additional effort is made on the part of the development team to get informal (undocumented) clarification of the requirements. This in turn leads to an under tested or untestable product.

Organizations should either invest in training their Business Champions appropriately for the requirements responsibility or empower their professional business analyst staff to lead the requirements elicitation, analysis and documentaiton process to get elaborated requirements to produce a testable, quality product.

• 
• +0
• 
• 

...
written by vmai002, July 07, 2010

This article is great. One thing I noted is that elaborative language used in documenting requirements is used further down the track to devise test scripts. I think both languages can be used interchageably depending on different levels of requirements.

• 
• +0
• 
• 

...
written by santoshkmhatre, July 07, 2010

A very well articulated document. Enough has been written by experts in this area. Only point I want to add is - whether we use restrictive or elaborative approach for requirements - The most important thing is to ensure that they convey what the stakeholders meant to the development & testing team. Ultimately,developers are the one who are going to write code based on those statements and testers are going to validate the functionality using those requirements statements.

Another point regarding usage of must,shall and will in requirements.
Must - Compulsory functionality without any exception
Shall - Although a mandatory functiopnality,alternate ways of achieving same goal are also acceptable.
Will - Optional functionality.

• 
• +1
• 
•