Writing Stylish Requirements

You knew it would happen eventually, the big ten rules of writing requirements has become the big twelve rules. Maybe scope creep isn’t such a bad thing after all. Writing style plays an important role in writing requirements too.

Background

The original series started with a summary of the ten rules to writing good requirements, and then we followed up with ten articles with details of each rule. Then we added another one – writing correct requirements. Today’s article brings us to twelve by adding an element of style.
The Big Ten Eleven Twelve Rules of Writing Requirements

1. Valuable
2. Concise
3. Design Free
4. Attainable
5. Complete
6. Consistent
7. Unambiguous
8. Verifiable
9. Atomic
10. Passionate
11. Correct
12. Stylish

Stylish Requirements

For Buzz Lightyear, in the movie A Toy Story, the difference between falling and flying was simply a matter of style.

Style can also be the difference between a well-crafted requirement and one that is hard to read. And style, applied consistently across requirements makes it easier to view them as a whole, and identify gaps and inconsistencies. This ease of comprehension matters when trying to achieve correct, consistent, complete requirements.

Elements of Style

Usually, when we talk about writing style, we are talking about grammar rules. Documenting requirements requires a specialized, almost esoteric form of writing. And this form of writing benefits from applying some consistent elements of style. We should use the same style when writing all of the requirements for a given product or project – and ideally for all projects within a company.

Styles are like elbows – everybody’s got them – so it isn’t reasonable to expect everyone to use the same style. Develop a style, and use it.

Here are some of the ingredients that go into our style recipe:

• Thou Shalt
• Prioritize Explicitly
• Pick The Best Perspective
• Non-Negative Waves
• Reference, Don’t Repeat
• Gender Indifference
• Syntactic Parallelism

Thou Shalt

The analyst shall use the word shall to express a requirement. Other acceptable words are must and will. When writing requirements, use phrases like “The system shall process…” or “The user shall be able to…”

Prioritize Explicitly

In More About Software Requirements by Karl Weigers, he pointed out his dissatisfaction with the way some teams capture prioritization implicitly in their requirements through the use of shall / should / may language. “Shall” requirements are high priority, “should” requirements are medium priority, and “may” requirements are low priority.

Ugh. What a horrible idea. I had not seen anyone doing this. Karl’s right, this is an awful idea. Especially when teams involve people who don’t share the same native language or culture. Priority should be called out explicitly.

By the way, Karl’s book is great. If you gather, write, or manage requirements, you should own it.

Pick The Best Perspective

Some requirements are written “The system shall…” and others are written “The user shall…” These two approaches represent two different perspectives. In an ideal world, one perspective or the other would be most appropriate for all of the requirements within a document. We would also have free energy, world peace, and total enlightenment.

We could force ourselves to consistently apply the same perspective for all of our requirements. Jumping through linguistic hoops to write this way would violate our rule of writing clear and concise requirements. For each requirement, we choose either “system” or “user” as most appropriate.

• The system shall process invoices nightly.
• The user shall input their shipping address.

Imagine trying to write either requirement the other way (replacing system or user with user or system respectively).

Non-Negative Waves

Another great suggestion from Karl. Don’t write requirements in the negative, write them in the positive. A couple examples:

• “The system shall not permit orders with more than 1000 items.” Write this as “The system shall only permit orders with 1000 or fewer items.”
• “The user shall not be able to access data to which he does not have sufficient authorization.” Write this as “The user shall only be able to access authorized data.” [Note – additional information about authorization would be required to make this complete. See the next tip.]

Reference, Don’t Repeat

The same concept, construct, or requirement may be repeated in multiple places within the requirements for a product. It should not be duplicated, it should be referenced. In the previous example, we used the requirement “The user shall only be able to access authorized data.” The will be other requirements around how authorization is defined and managed.

We could duplicate an explanation of what authorization implies in each place where we reference it. What would be more manageable would be to reference a single explantion of authorization.

Gender Indifference

A hot topic for grammarians is the proper use of gender in documents. Should we use “he” or “she” or “s/he” or “they?” What about “one” or “the user?” This is a matter of preference. We prefer indifference.

We arbitrarily define the gender of any particular user as male or female within a requirement or example. We try and maintain a balance by having roughly half of our entities be female, and half male. In my personal opinion, this makes for stronger writing than using the contrived s/he or a plural form like they.

When defining actors and use cases, the actor’s gender is generally not specified. The actor is described as a role. The text of the use case, especially when using an informal use case, is where this style is applied. We maintain gender-consistency for any particular actor in a single use case, we don’t try and assign genders to actors and maintain consistency across all of the use cases.

When defining personas and writing user stories, we will match the gender usage in the story to the gender of our persona.

Syntactic Parallelism

This is an obnoxiously complex way of saying “write with consistent structure” – but it at least got you to scroll down and read this far.

“He came, he saw, he conquered” is much more powerful than “He came, he saw, his foes were conquered.” Likewise, “The system shall process the request, retrieve the results, and present them to the user” is better than “The system shall process the request and retrieve the results and the user shall view them.” [Note: The example above violates the atomicity rule, but is illustrative.]

Conclusion

Style is not something that can be quantified any better than art can be quantified. The best we can do is follow guidelines and apply our skills. And as good writers will attest, these are guidelines. It is better to violate them when appropriate than to rigidly adhere to them in spite of the awkwardness of the results.

Having a consistent style will help with readability of the requirements. Define your style and stick to it.