When building a software system, requirements form the bridge between the stakeholders involved and the development team. According to IREB, a requirement is defined in this case as a perceived need by stakeholders, the capability or property that a system shall have or a documented representation of a need, capability or property. Requirements are the link between the problem and the solution and must be communicated to stakeholders and the development team. Vocal communication between the people involved is possible, but this form is hardly persistent or consistent in daily business. Therefore, requirements are documented in different forms.
Broadly, requirements can be written down in three different ways within the IREB standard:
- Natural language | The requirements engineer uses their native or a foreign language for documentation.
- Templates | The requirements engineer uses a structured template to note the requirements.
- Models | The requirements engineer uses a pre-defined modelling language, e.g. UML 2.5, for documenting the requirements.
Out of the three methods listed above, natural language is most widely used for documenting requirements. According to a study by Zhao et al. (2021), at least 61% of the participants asked said they use natural language to document requirements within their software development projects.
Natural language has various advantages and is one of the favourite techniques for documenting requirements. On the one side, natural language is used by everyone daily. Everyone speaks at least one language as their native language that can be used for requirements documentation. Moreover, natural language can be learned quickly and adapted to specific topics and surroundings. This flexibility makes natural language one of the most preferred techniques for requirements documentation within software development projects.
However, natural language is prone to misinterpretation. It has evolved over millennia and is still changing today. The usage and understanding of natural language depend on different aspects. Spoken natural language is used in a defined context, where every speaker or listener can ask questions or provide feedback for clarification. Moreover, when using the language in a face-to-face conversation, the participants build a knowledge base of implicit knowledge that helps them understand the context. Unfortunately, these aspects are not available if the natural language is used in its written form for documenting requirements. In that case, we often find faulty written texts with different connotations causing people to understand the documented requirements differently. Most of the time, natural language is used because it is easy to learn. However, if the structure of the requirements gets more complex, other documentation techniques, such as graphic models, should be preferred in order to reduce complexity. Natural language is just one way to document requirements, but it is also often used because the knowledge of other documentation techniques is unavailable within the project.
But how can a requirements engineer address this issue?
The International Requirements Engineering Board (IREB e.V.) provides several pieces of advice that we have been using for years to deal with the rising challenges of using natural language for documenting requirements. One recommendation for a requirements engineer when writing requirements in natural language is to write short sentences. The rule of thumb is to have just one requirement per sentence. Additionally, the requirements engineer should pay attention to the document’s overall structure. By using a standardised template and design for documenting requirements, the reader can recognise the stated requirements more effectively. A requirements engineer can also use phrase templates for structuring written requirements. The user story template is a well-known example of a phrase template often used in agile surroundings. To avoid inconsistency concerning the terminology used, the development team – the requirements engineer in particular – should define the terminology within glossaries. Moreover, the requirements engineer should avoid vague, ambiguous phrases when documenting requirements. Finally, the requirements engineer needs to review the documented requirements to identify common linguistic pitfalls such as incomplete comparisons, using the passive voice, etc.
Our experience shows that even if a requirements engineer learns this advice in a structured training programme, much more practice is needed until it is internalised in daily requirements documentation activities. Especially the work of inexperienced requirements engineers needs to be reviewed and verified by trained requirements engineers with several years of requirements documentation experience in writing consistent and effective requirements for the development process. However, this statement should not be seen as a prerequisite for reasonable requirements engineering; it only emphasises that effective requirements documentation in natural language can only be achieved by constant training and the willingness to self-improve one’s writing skills.
At ERNI, we have several years of experience documenting and managing requirements throughout their development life cycle. Besides structured training programmes, we are ready to support your development team in writing effective requirements. We cover all aspects of requirements documentation and management necessary for your development project’s success and for effective stakeholder communication within your development endeavour. As a platinum partner of IREB e.V., we are competent in all state-of-the-art requirements techniques and know how to address your challenges accordingly.
Sources:
Zhao, L., Alhoshan, W., Ferrari, A., Letsholo, K.J., Ajagbe, M.A., Chioasca, E.V. and Batista-Navarro, R.T., (2021) Natural language processing for requirements engineering: A systematic mapping study. ACM Computing Surveys (CSUR), 54(3), pp.1-41.