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

ArgonDigital - enterprise automation experts

Share This Post

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.”
  1. 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.

More To Explore