How Plain Language Can Help You Flush Out Risky IT Docs

I have blogged recently about Plain Language here. This was in the context of poor-quality RFP and bid-response docs. The basic premise: if you apply some basic Plain Language checks to your writing, quality will increase.

In this post, I wanted to look at the IT space to see how we can improve documented requirements.

As background, people like Tom and Kai Gilb argue for improving requirements quality by rewriting them in a notation (Planguage) that is measurable and testable. This is really great if your team is able and willing to adopt that approach. In most business organizations, however, it is a bridge too far. This is because Bas (Business Analysts) are not conditioned to translate informal English into mathematical statements.

Here I argue for a less radical and more digestible alternative; running a basic plain language check. This leads to dramatically improved requirements quality. More importantly, it is very workable in pretty much all organizations.

How does Plain Language analysis help?

For starters, let’s set some context on Plain Language. Plain Language (sometimes called Plain Writing) is all about clear, concise communication. If you want to see how and why the US government is sponsoring plain language, check here.

Let me first give a non-IT-related before and after example from http://www.plainlanguage.gov/examples/before_after/index.cfm :

“When the process of freeing a vehicle that has been stuck results in ruts or holes, the operator will fill the rut or hole created by such activity before removing the vehicle from the immediate area.”

vs.

“If you make a hole while freeing a stuck vehicle, you must fill the hole before you drive away.”

This example shows two things: (1) a long, complicated sentence and (2) passive language. You can see the passive highlighted in maroon. Both sentences attempt to communicate the exact same thing. You be the judge of which is clearer.

Are you agile or waterfall? Does it matter?

You may be capturing your initial requirements using the ‘big fat doc’ approach or you may capture them as stories in a 100 percent agile environment. Either way, if you apply Plain Language checks, quality will improve.

Since we work with a good number of corporates who still use BRDs (Business Requirements Definition), I will show examples and analysis from BRDs but all of the principles of plain language apply equally to requirements captured as part of an agile approach.

The value of identifying long sentences

Long sentences often mask multiple requirements and can often contain multiple meanings and ambiguity. We categorize them as sentences in excess of 25 words.

Here is an example of a long sentence in a recent BRD for a financial institution:

“Prices received electronically daily from the Fund Accountant via FTP and email, except for the Growth Stock Fund, which prices monthly and for the bi-monthly price receipt for Fixed Income  funds”

So here are the immediate issues:

1. Multiple Requirements: There are actually three rules embedded in this sentence. A rule pertaining to ‘general pricing,’ a rule pertaining to the ‘Growth Stock Fund’ and rules for ‘Fixed Income Funds’
2. Ambiguity: Is bi-monthly, once every two months or twice a month?
3. Ambiguity: Is daily business day only?
4. Ambiguity: Are Growth Stock Funds and Fixed Income funds also received electronically? Or is the ‘except’ clause inclusive of the receipt mechanism?

What is Passive Language and why it matters?

It is common to find that people are unsure what passive language is. Let me give a simple example first:

“Quality is monitored” vs. “We monitor quality”

Notice that the first version contains ‘is monitored.’ It does not specify the actor, i.e., who or what is responsible for monitoring. The formal definition of passive language is a statement where the noun precedes the verb. In our example, ‘quality’ is the noun, with ‘is monitored’ coming second, masking the active form ‘to monitor.’

Passive language also allows you to omit specifying the person or entity responsible for performing the verb.

For IT systems, where completeness of specification is important, that omission can lead to guesswork and misinterpretation by developers. If you convert passive into active language, it will often reveal missing actors and incomplete specifications.

Omitting the actor also means less testable requirements. Agile stories and use cases by their nature emphasize the active form, which is why they are very effective capture mechanisms. On the other hand, BAs can tend to write general business and technical requirements in the passive voice.

Here is just one example from a real IT program spec in a BRD (Business Requirements Definition):

“Those transactions/fields that the user is authorized to input will be submitted to ZHG on the mainframe.”

Immediate issues:

1. Missing actor. Who or what authorizes?
2. Who or what submits to ZHG (renamed from the real system)?
3. We need an exact set of conditions that allow each step to occur. This statement actually contains two distinct rules. It would be better to split them as two separate statements (or steps) and link them in a flow or story.

Further, the following set of questions pop out:

4. Are transactions and fields using different permissions?
5. What are the transactions?
6. What are the fields?

While points four through six are not explicitly associated with passive analysis, this kind of looseness is often spotted in the vicinity where passive language is present.

When we scanned the entire doc, it showed that 18.75 percent of all sentences in the BRD contained passive language.

So reviewing just for passive language often uncovers significant degrees of looseness and risk, and the amount of passive language present increases risk.

Simple steps to reduce risk

What simple steps can you take to improve quality?

1. Scan for and eliminate long sentences: Aside from being harder to interpret, long sentences often mask several different requirements. They are thus hard to track and estimate for. Splitting up the sentence is a first step.

2. Rewrite passive with a verb-driven approach: Active (verb preceding noun) rather than passive (noun preceding verb) language makes for clearer requirements. It forces an explicit reference to the ‘actor.’ The actor is the person or entity responsible for performing the action. From an IT standpoint, this reduces ambiguity and yields much more testable requirements.

Summary takeaways

–          Plain Language can uncover high risk in your requirements.

–          Long sentences and passive language; these are your enemy.

–          Eliminate passive language and long sentences from your IT requirements to reduce risk.

Don’t forget to leave your comments below.