Reqlish: Part I: English Usage and Syntax for Software Requirements

Justin Burrows says:
Hey James. I got a sooooooooooooper dorky idea: Let's do our blog post on Requirements English (I'm calling it Reqlish) over Skype.

*Justin Burrows is pleased with himself *

James Hulgan says:
LOL. Alright, ready set go.

Justin Burrows says:
We're brought up to mind our p's and q's, but is good English really suited to Requirements? Especially when working with global teams, a simplified "pidgin" may actually work better for requirement documents. The pidgin that I use has this consistent structure similar to simple, formal language:

[Subject] [Verb] [Object] [Exception/Modifier].

But I also drop articles (e.g. a, the, an) and instead use all caps to indicate specific systems.

James Hulgan says:
Yes, "proper" grammar does not always buy us what we want as requirements analysts--that the requirements are easily consumable and understood. Often, the way in which requirements statements are structured grammatically is ignored, but it is crucial to how well the requirements are understood. Some grammatical purists may disagree and claim that we should always use proper rules of grammar in our writing. I would respond by staking out two possible positions with respect to grammar:

1. The Orthodox: Think your junior high or Freshman English comp teacher. Motto: “There is a Correct and Proper English Grammar, and anyone who deviates from that grammar deserves to be publicly humiliated.”


2. The Pragmatist: Not sure there is an archetypal linguistic pragmatist, but I think of my sophomore English teacher who encouraged my fiction-writing. Motto: “Grammar is a tool: Use it and modify however you can in order to get your point across the best way possible”.

As a requirements analyst, we have to be pragmatists.

Justin Burrows says:
I find this "Reqlish" is often a battle between logic and ear. For example, saying "a equipment" instead of "a piece of equipment" sounds awful to me, but perfectly normal to consumers to whom English is a second language.

But, James, I put it to you:

Are these grammar shortcuts that this crap up anymore with which the latent grammar nazis on the team will not put?

James Hulgan says:
I don't think that we should care so much about the grammar nazis. We should spend the effort to ensure our requirements are grammatical only if it serves the purpose of ensuring that the requirements are unambiguous. If making the requirements "ungrammatical" furthers the cause of consumability and understandability, then it is worthwhile to discover the structures which make this possible. Not too many people these days, besides crotchety junior high English teachers, believe in "one true grammar" for English anyway.

Justin Burrows says:
I think there are a lot of closeted Junior High English Teachers out there (and you know who you are-- Alright is a word, btw. :P). Do you think there are "rules" that Reqlish would play by?

James Hulgan says:
Well, it probably depends on the project, but I think something like [Subject] [Verb] [Object] [Exception/Modifier] is a good start. Trying to avoid ambiguity is an awesome goal, but to very loosely paraphrase John Searle, “Syntax does not suffice for semantics”. In other words, one particular grammatical structure is not guaranteed to be less ambiguous than another.

*Justin Burrows rings the idiot bell.*

Justin Burrows says:
Ok, smart guy, want to explain the distinction between Syntax and Semantics?

James Hulgan says:
Briefly, a language's syntax is the rules for how items (words) in a sentence of a language can be arranged. Semantics is the meaning of the strings in a particular language. So, while the meanings of sentences certainly depend on syntax, a particular syntax is not sufficient for conveying meaning.

Justin Burrows says:
Huh…

James Hulgan says:
There, like, has to be a balance, man.

Justin Burrows says:
Ok, I can dig it. Can we talk more later about building a formal syntax for Reqlish?

James Hulgan says:
Sure! I chatting syntax. Let's go more into the subject-verb-object structure and what structures are most easily understood. And next time let's give people some practical examples to use in their own documentation.

The One Thing You Need To Be A Team Player

Mike A’s earlier post on being useful, Thomas the Tank Engine on Software Requirements, brought to mind thoughts I’ve had about what it means to be a team player. What Mike defines as being useful, I consider a top characteristic of a team player—doing what is best for the team to succeed on the project.

Do a search on the topic “Team Player” and you’ll find a lot of articles about the characteristics of a good team player or how to be one. But, you won’t find much about the objectives of a team player. It’s one of the classic requirements problems: lots of strategies and solutions, but no one is stating the goal.

Understanding the goal is important, for example:

• I’ve worked with people who defined the objective as making everyone happy. Unfortunately, “happy” is sometimes a short-term thing. What makes people happy now, may make them very unhappy later, if the happiness comes at the expense of unnecessary work or a less successful project.


• There are also the well-intentioned people who work very hard to do their best, who end up unthinkingly maximizing their own performance at the expense of the team as a whole.

My objective as a team player is to do what I can to maximize the performance of the team to meet the goals of the team. The “Team Player” search results provide a lot of strategies for doing that. I think being useful is one of the best.

Oh, and, as Mike implied, eating your vegetables usually won’t make the top 10; but, that’s no reason not to eat them.

Who Does Your Consultant Work For?

There is an interesting article by Robert Cringely at pbs.org about IT consultants. I disagree with the categorization of types of consultants however the article is interesting because he mentions the following case:

"What led me to write this column were the troubles of a local company here in Charleston -- American LaFrance, the storied maker of fire engines. American LaFrance was last year spun off from Freightliner, the big truck manufacturer, which agreed to maintain the company's computer systems for a few months while the new American LaFrance bought its own systems with the help of a big IT consultant that rhymes with I-B-M. At the time of the cutover the project was months late and millions over budget. The company suddenly had no idea where it stood in any part of its business and today is in bankruptcy likely as a result."

He then goes on to suggest that the issue was primarily one of bad requirements. The story reminded me of a presentation that I attended by a turnaround specialist. He made a living going into trouble companies and fixing them. He said that he could find all his customers by just following around PeopleSoft (or any large ERP vendor's) salespeople.

Wherever they sold their software, the failed software implementation would take down the company!

He said that the primary reason that the software failed was not because the software was bad, but because management wasn't willing to force the business users to change their processes to accomodate the off the shelf software.

As a result, the IT team had to accomodate every whim of the business.

Sound familiar?

What Oprah Can Teach You About Software Requirements

My wife's a fan of the Oprah Winfrey Show (yes, I've been known to watch it from time to time myself). A few days ago, my wife told me about a woman who was on the show. The woman was telling Oprah about her philosophy that people only ever have good intentions, even when they're doing something that's infuriating to you.

Somebody cut you off in traffic? Maybe they were trying to get home to a sick child. Somebody else tell you that you can't take that training class you were promised earlier this year? Maybe those savings will let your office-mate keep his job. If you're willing to look for them, you can usually find a possible good intention behind people's actions. But why should I care about their reasons? I'm hacked off!

The speaker's point wasn't that we should be nice to other people because of their intentions. Instead, it was that we'd all be much happier if we assumed the best of others' intentions. Rather than getting mad because Sally is out to get me, or Tom is just plain mean, or Jack is a jerk, you can be happy because they're each trying to do something good. Sound a little too Bobby McFerrin? A little too "turn that frown upside down," or "buck up little camper?" It certainly did to me.

But, given my rather nasty mood one day, I decided to give it a shot. It couldn't make me feel any worse, plus it would get me brownie points at home. For the past week, whenever someone has done something that annoys me, I've looked for a possible reason why they did what they did (I'm not actually asking anybody why, just pondering possibilities). And it's working.

For example, when I thought about why somebody was driving so fast, or tailgating me, or zipping in and out of traffic, I wondered who they were in such a hurry to see. That simple change of perspective made a huge difference in how I perceived their actions (and by proxy, them as people). And then I thought about the people I'd be in a hurry to see, which led me to think about my friends and family, not about the reckless driver.

Before you ask, "And this has what, exactly, to do with product management?," (unless you already have), I'll get to the point. In our work, we deal primarily with people, and dealing with people is hard. It's easy to let someone else's actions (or inactions) frustrate me. But now I have a tool to help me reduce that frustration. And more importantly for my customers, asking, "Why did she do/say that?" is a great way to discover the real requirements hiding just out of sight.

Go on ... give it a try. Hopefully it'll surprise you, too. And if not, I'm sure Oprah would love to hear from you!