Blog: The meaning of words

Defining requirements is basically a simple task. Listen to what the customer wants and write the requirements in a suitable format so that the developers can implement them. However, the task involves many challenges and potential pitfalls.

Development models vary and requirements can be user stories or more formal descriptions in the specification document. Still, almost without exception, they are described verbally, and in Finland usually in Finnish, Swedish or English.

Challenges of natural language

Language is communication from author to reader, and it is likely that there are differences in the knowledge and experiences of the author and the reader. Therefore, the text may be difficult to understand or some ambiguous expression may be misunderstood. For example, the following issues often pose challenges in requirement texts:

• Professional slang and abbreviations
• Unclear words
• Confusing and complex sentence structures
• Excessive storytelling
• Language barrier

Slang and abbreviations 

It is natural to use professional jargon and abbreviations in your own team. However, if you want to produce text that is understandable to other stakeholders, slang should be replaced with clear common language. But frequently the requirements of e.g. technical systems require precise professional terms. These can be made into a separate glossary, where their meaning is clarified to stakeholders with the necessary precision. This also ensures that the same term is always used for one concept. Abbreviations can be grouped in the same glossary.

Unclear words

Adjectives are often inherently inaccurate, lacking a clear metric or benchmark. Unfortunately, vague attributes such as "easy to use", "standard" or "fast response time" are still often seen in requirement texts. Embellished writing is irrelevant unless verifiable metrics can be included. Ease of use can be addressed, for example, by determining the number of mouse clicks required to perform a task.

Confusing and complex sentence structures 

In mathematical logical sentences, different operators have certain priorities (NO, AND, OR), and the statements can also be clarified with parentheses if necessary. In natural language, these means do not exist, but the sentence structure must be formulated so that misunderstanding is not possible.

For example, the following sentence: "Customers using a bonus card or discount code and ordering for more than €100 will receive free delivery" can be interpreted in two different ways:

1. bonus card OR (discount code AND over €100)
2. (bonus card OR discount code) AND over €100

Indeed, it is often better to break down long sentences containing complex terms into separate sentences or tables. If the first interpretation above was correct, it could be worded, for example: "Holders of the bonus card will always receive free delivery. In addition, free delivery will be given if a discount code is used and the order is worth more than 100 euros."

Excessive storytelling 

Many speakers like to talk and continue their story with different filler words and sidetrack from the issue. The same then happens easily when writing. When writing requirements, one should carefully consider the meaning of each word. Similarly, for each sentence the writer should consider whether it is necessary for understanding the matter or unnecessary stuffing. Repeating things is absolutely pointless. It should be remembered that unnecessarily lengthened text slows down reading and makes any changes more difficult.

Of course, the text should not be too brief. It must contain everything necessary but nothing extra.

Language barrier 

English is widely used as a working language in Finland and other non-English speaking countries. However, many who speak the language (over 75%) do not speak it as their mother tongue. Although the language is common, it is not particularly easy, due in part to the richness of vocabulary. This results in a lot of potential comprehension problems. What is the solution? The above suggestions help a lot here too. It may be worth considering whether it is always mandatory to use English or whether a project with a fully Finnish-speaking team could be defined using Finnish language.

Through experience and education, we learn to be better users of a foreign language. If the text is important, you should always check it with another reader. Professional help is also available. WriteIt (a subsidiary of ImproveIt) offers English language checking with solid experience. You can read more about it here.