Writing Rules

Even an analysis that is excellent from a technical standpoint can be completely ruined if it is vague or ambiguous, leaving readers unsure of the exact meaning. Failing to make outputs clear and unambiguous frustrates readers and wastes valuable time on clarifications. In this chapter, we will present common causes of ambiguity and provide tips on how to avoid them.

Avoid Ambiguous Words

A good analysis should not trigger questions like "What did they mean by this?" Using words that create uncertainty is a common source of confusion and should be avoided. For example, a writer should avoid using "and/or" statements, as they leave the interpretation up to the reader and can be understood differently by different people: "The system requires entering client name, client birthdate and/or client age."

Vague Statements

Do words like "probably", "perhaps", or "maybe" mean yes or no? Does "sometimes" or "usually" mean once a minute or once a year? How much exactly is "several", "some", or "as much as possible"? An analyst should always be precise so that the audience does not have to guess.

Etc., And So On, Among Others

"The screen displays client details: name, age, etc." This information is incomplete and can neither be verified by stakeholders nor implemented by developers. You have two choices: complete the information, or clearly indicate that it is yet to be specified, for example, by labeling it "TBD".

Every, Each, All, Any

Why is it risky to state "The system shall display all product attributes" or "The table must be sortable by all columns"? At first glance, these seem like clear requirements. However, in practice, they act as a time bomb because they can stop being valid without anyone noticing. For example, a new product attribute might be added that should not be displayed on the screen. Or a new column might be introduced that should not trigger sorting. Suddenly, the original requirement is no longer true because not all attributes are displayed and the table is not sortable by all columns.

This inaccuracy can lead to incorrect implementation, and it becomes even more dangerous if such requirements form part of a commercial contract between a customer and a vendor. It allows the project scope to expand indefinitely and presents a significant project risk. Requirements formulated this way leave too much room for speculation. Stakeholders might say, "You need to do this feature for free because it is in the requirements," and technically they would be right, since the requirements say "all product attributes" and "by all columns."

There are exceptions, of course. For example, a graphic design manual describing general user interface behavior may instruct developers to make "all submit buttons green." This is acceptable because it defines a global standard that all screens must follow.

General, Common

Every time we see headings like "General Requirements" or "Common Functions", we know we are about to deal with a collection of unsorted, unrelated artifacts that someone was too lazy to categorize properly. We call this a black hole that grows larger over time, swallowing everything until its contents become unmanageable. Avoid this approach and find an appropriate label that accurately describes what the category actually contains.

To Process Something

The issue with the word "process" is that it is too abstract and does not clarify what exactly should happen. For example, what does the system actually do when "it processes the order"? This is not clear until more details are added. Replacing it with a specific action, such as "The system stores the order and marks it as 'New'", makes it clear to everyone.

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

Active Instead of Passive Voice

Every action can be expressed in two ways: using the passive voice or the active voice. The active voice emphasizes who performs the action: "John broke the window yesterday." The passive voice, on the other hand, is used when the actor is unknown or intentionally hidden: "The window was broken yesterday." While this can be useful in everyday conversation, it is a risk in analysis: "This interface is called to get a list of sold cars" – who calls whom? Always use the active voice so it is perfectly clear who or what triggers the activity: "The Car Management System calls the SysCAR 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 with unnecessary pleasantries like "Hello" or "I would like to ask you" in every question, advising them instead to get straight to the point. The same approach should apply 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 core facts and make the text unnecessarily wordy. Don't write novels; use simple expressions and keep your outputs as concise as possible.