Writing Rules

Even an analysis which is excellent from the technical point of view could be totally ruined if it is vague, ambiguous, and readers have doubts about the exact meaning. Not putting enough attention to making the outputs clear and unambiguous frustrates readers and is ineffective for both sides as clarifying issues takes valuable time. In this chapter, we are going to present common causes of the ambiguities and provide tips to avoid them.

Avoid Ambiguous Words

A good analysis should not trigger questions, such as "How this was meant?" Using words that cause unclarities about the meaning is a common source of confusion and should be avoided. For example, a writer should avoid using "and/or" statement as it leaves the interpretation up to the reader and could be understood differently by different people: "The system requires entering client name, client birthdate and/or client age."

Vague Statements

Do "probably", "perhaps" or "maybe" mean yes or no? Is "sometimes" and "usually" once a minute or once a year? How much is "several", "some" or "as much as possible"? Analyst should always be precise so that the audience does not need to guess.

Etc., And So On, Among Others

"The screen displays client details: name, age, etc." The information is not completed and can neither be verified with stakeholders nor implemented. There are two choices: you need to complete the information or indicate the information is yet to be specified, for example, by labeling it "TBD".

Every, Each, All, Any

Why is it wrong to state "System shall display all product attributes" or "The table must be sortable by all columns"? Well, at first sight, it is quite a clear requirement. However, in practice, it represents a time bomb: it could stop being valid without anybody noticing. For example, a new product attribute could be added, but it is not required to be displayed on the screen. Or a new column is introduced, but clicking on it should not trigger sorting. Then the original requirement is not valid anymore as not all attributes are displayed and the table is not sortable by all columns.

This inaccuracy may lead to the wrong implementation, but it could be even more dangerous if such requirements create a contract between the customer and the vendor. It allows inflating the scope infinitely and presents a significant project risk. Requirements that are formulated this way give a lot of space to stakeholders to speculate about the scope. They could say, "You do this feature free, because it's in requirements" and they are right because the requirements say "All product attributes..." and "..by all columns.".

There are exceptions, though. For example, a graphic design manual describing the general behavior of the user interface may instruct developers to have "all submit buttons green". This is acceptable, as it defines a standard all screens must follow.

General, Common

Every time we see something like "General requirements" or "Common functions", we know we are going to need to deal with a bunch of unsorted, unrelated artifacts that somebody was too lazy to sort out and put into concrete categories. We call it a black hole that will get bigger and bigger over time, swallowing everything until its contents become unmanageable. Avoid it and find an appropriate label instead, which will describe what the category really includes.

To Process Something

The issue this word represents is, it is too abstract and does not articulate what exactly should happen. For example, what does the system do if "it processes the order"? It is not evident from the statement until more information is added. Replacing it with something more concrete such as "System stores the order and marks it as 'New'" makes it clear to everybody.

There is a great summary of the most common ambiguous terms and the ways to improve them in the Software Requirements book. We present them in this chapter

Active Instead of Passive

Each action could be expressed in two different ways, using a passive voice and active voice. Using the active voice emphasizes who performs the activity: "John broke the window yesterday". The passive voice on the other hand, is used in cases when the actor of the activity is not known or is intentionally left hidden. For example, "The window was broken yesterday". As it might be sometimes useful in common conversation, it represents another time bomb in the analysis: "This interface is called to get a list of sold cars" - who calls whom? Always use active voice so that it is clear who or what is a trigger of the activity: "Car Management System calls a SysCAR's interface to get a list of cars."

Right to the Point

The popular Q&A platform stackexchange.com encourages users not to waste others' time by typing unnecessary statements such as "Hello" or "I would like to ask you" with each question and advises them to go right to the point. The same should be applied to all analysis outputs. Phrases like "In this section, you can find a list of...." or "In case you choose the item by clicking on it..." distract the reader from the important facts, make the outputs unnecessarily wordy, and going through them takes time. Don't write novels, use simple expressions, and try to make the outputs as concise as possible.