The Most Complete Guide to Requirements Management and Traceability
The Do’s and Dont’s for Writing Requirements
Table of Contents
If you’re like most people, you probably don’t enjoy writing requirements. It’s not the most exciting thing in the world, but it’s a critical part of product development. A better requirements document can save your organization a fortune with clear communication between the developer and product stakeholders. This, in turn, reflects across the organization, including greater transparency, lesser rework, and improved productivity.
While every organization has different requirements and methodologies, the fundamentals for writing requirements remain the same. In this article, we will share a few tips that can help you enhance your requirements writing skills and help you write clear and crisp Requirements Specifications.
What is Requirements Specification?
Requirement specification, also known as documentation, is a process of jotting down all the system and user requirements in the form of a document. These requirements must be clear, complete, comprehensive, and consistent.
During the capturing activity, we gather all the requirements from various sources. During the analysis and negotiation activities, we analyze and understand those requirements. Now, we must prepare a formal document explaining those requirements. That is what the requirement specification is. To be precise, it is the process of documenting all the user and system needs and constraints in a clear and accurate manner.
What do “Best Practices” in Requirements Management mean?
It is so interesting to me that everyone talks about wanting training in “best practices”. This term is often used to describe the kind of consulting we might provide as well. What does that really mean? I believe all of us have fed into the myth that best practices can be the basis for training individuals. Best practices are not trained, they are experienced.
If we compare the best practice approach to nature, we know that it is not only the strongest but the most prolific species that survive. That’s one of the reasons it is so difficult to change processes in an organization. Think about that for a moment. The strongest and most prolific probably describe the majority of individuals you have in just about any group in your organization. I have seen this over and over in the System Engineering field. The strongest and most prolific engineers have often been doing their job for many years and have a specific way they do this job. Asking them to try new techniques and tools is often futile, as they don’t know how this is going to improve the already wonderful job that they are doing. Their practice is going to survive if we continue to shove a best-practice approach at them.
Challenges When Writing Requirements
There are various challenges people face when writing requirements.
Poor Paperwork – In some organizations, documentation of processes is either nonexistent or not up to par. In this case, collecting requirements becomes a two-step process: first reverse engineering the existing process, and then identifying areas needing improvement and optimization. To confirm that requirements are fleshed out and accurate, it’s key to identify key stakeholders and subject matter experts, engaging with them directly. Drawing business process maps and visualizing workflows are two excellent ways to do so. This aids in the elimination of incorrect assumptions while also providing a complete picture. Drawing process maps and displaying processes are two useful approaches for this purpose.
Contradicting Requirements – When stakeholders have different priorities for their business goals, this leads to requirements that conflict with each other. In cases such as these, the responsibility of a business analyst is to document all requirements in detail, identify which requests oppose each other, and allow stakeholders the opportunity to decide what takes priority.
You can’t make decisions without hearing stakeholders’ input, and as a business analyst, you may have some ideas about what should be prioritized. It’s still crucial to hear the perspective of stakeholders. Setting up a poll might be one of the methods to obtain clarity on what matters most to the majority of stakeholders.
Unavailability of User Input – A few reasons may contribute to the unavailability of end users, and each requires its own resolution. For instance, sometimes end users are so preoccupied with their daily work that they’re unwilling to partake in requirements-gathering activities.
In such cases, the best a business analyst can do is to limit the number and length of engagements. Prior to the meeting, doing as much research as possible will help to make the discussion more organized and informative. It’s almost like turning requirements gathering into requirements validation sessions. defining focus groups and identifying the most suitable end-users for each group
Focusing on Interface Instead of Experience – Many stakeholders and end-users have a clear vision of how the new solution should appear, but they don’t know what it should accomplish. Any system’s user interface is crucial, but it shouldn’t define or interfere with the functionality.
Business analysts should always remember to keep design and functional requirements separate in their documentation. By using more general tools such as diagrams, user stories, or low-fi prototypes rather than design drafts, they can maintain focus on the functional aspects of requirement gathering.
Stakeholder Inputs – When stakeholders or end-users try to tell designers how the system should work instead of what the system should do, it can lead to suboptimal designs. To head this off, validate each potential ‘false requirement’ by asking ‘why?’ until you arrive at the real problem that needs solving.
Communication Issues – Among the issues that can lead to miscommunication between a business analyst and other parties are language barriers, wrong assumptions, insufficiently explained vocabulary, and overuse of technical terms.
The ideal approach to avoid this problem is to interact frequently and develop two-way conversations. Document the needs that you’ve discovered and submit them for peer review and criticism to a variety of subject matter specialists, create a glossary of jargon and double-check premises.
10 Do’s and Don’ts When Writing Requirements:
Do #1. One At A Time – Each requirement should be treated as a discrete test case. Conjunctions such as and, or, and so on should not be used because they might lead to missing out on requirements. This is particularly crucial since terms like these may cause software developers and testers to overlook requirements. Splitting complicated needs into smaller parts till each one can be tested separately is one way to prevent this from happening.
Don’t #1. Talk “What” Not “How” – The focus should be on what the system will do, not how it does it. Additionally, avoid delving too deeply into design topics such as field names, programming language objects, and software objects. If you find yourself discussing these topics in the Requirements Specification Document, take a step back – this likely means you’re getting too specific.
Do #2. Traceability – Traceability in project management refers to ensuring that requirements are linked to other components in the project. This allows project managers, developers, and stakeholders to keep track of a requirement’s entire lifecycle from beginning to end in all directions as well as with other parts of the system. If you manage traceability properly, you can avoid code that does not correspond to any requirement (‘stray’ code), and ensure that every test case covers at least one requirement. You can make requirements traceable by labeling them with a unique identifier and providing information about their source in a central repository accessible to all team members.
Don’t #2. No Exceptions – A requirement should not have an escape clause. For example, “The system shall determine the number of login attempts, except when the user has clearly entered an incorrect username”.
Do #3. Feasible – Ensure that the project budget and timeline are feasible, along with available resources. If this condition can support the requirement, then it is possible to move ahead with the plan.
Don’t #3. Say No to “let-out” Clauses – Try to stay away from let-out phrases such as but, except, and only if necessary.
Do #4. Consistency – Maintain a consistent level of detail. For example, for user requirements, an end-user should be the subject of every sentence. Similarly, for system requirements, a system should be the subject of every sentence.
Don’t #4. No Abbreviations – Every requirement should be a full sentence without any acronyms or jargon.
Do #5. Active Voice – Always write in an active voice, making sure one of the actors is the subject of every sentence.
Don’t #5. Don’t Be Ambiguous – Do not use Ambiguousterms such as approx, etc., and more terms like that in the requirements document. Make sure to explain the requirements in such a way that everyone involved understands them correctly. Vague statements can lead to misinterpretations and can cause conflicts between various stakeholders.
Do #6. Subject & Predicate – For every requirement, there must be a subject (user/system) and a predicate (intended result, action, or condition).
Don’t #6. Speculations Can Cause Damage – Do not guess; do not make lists of features that are out of the question. Saying you want a system to handle all unexpected failures is pure fantasy since no system will ever be 100 percent what you desire it to be. Avoid duplication and contradictory statements.
Do #7. Verifiable – Another thing to keep in mind when organizing requirements is that they should always be testable. This means it needs to be possible to verify the system meets the requirement in question. This also links to our next point – traceability. If a requirement is full of vague terms, then it becomes harder to analyze and verify if the system actually meets these standards Performance-wise. Therefore, as much as possible, aim for clarity and precision in your language so that Requirements gathering isn’t an ambiguous process.
Don’t #7. Avoid Options – Do not offer ideas or options. You can spot these in any statement that includes the phrases may, might, could, or ought.
Do #8. Correct – Make sure every sentence is complete and grammatically correct with a proper subject, verb, and predicate.
Don’t #8. Do Not Talk in Future Tense – Do not refer to a yet-to-be-defined requirement. Your goal is to make the document as pleasant to read as possible.
Do #9. Focus – Establish focus by eliminating rambling, overlong phrases, and references to out-of-date papers.
Don’t #9. What Should be Used And Where? – “Shall“ should be used where requirements are being stated, “Will” should be used to represent statements of facts; & “Should” to represent a goal to be achieved.
Do #10. Organized Paperwork does Wonders – Keep requirements organized in one place to improve the readability of your document and avoid wasting time cross-referencing multiple sources.
Don’t #10. Do Not Use Unknown Terms – Do not use unknown terms like “user-friendly, versatile, and robust” as can create difficulties when trying to define test cases. These words often carry different meanings for different people.
Visure Requirements ALM Platform
Visure is one of the most trusted application lifecycle management platforms that specialize in requirements management for organizations of all sizes across the globe. The major partners of Visure include business-critical and safety-critical companies. The company integrates through the whole Application Lifecycle Management processes including risk management, issue and defect tracking, traceability management, change management, and various other areas like quality analysis, requirements versioning, and powerful reporting.
If you’re looking for a requirements management tool that will help you with both functional and non-functional requirements, check out Visure Requirements. With this platform, you can easily create, manage and track all your project’s requirements in one place.
Conclusion
Requirements specification is a critical process in software development, but it can be challenging to write good requirements. The 20 tips we’ve provided should help you write better requirements, making the process smoother for everyone involved. If you want to take your requirements writing to the next level, consider using a tool like Visure Requirements ALM Platform. Request a free 30-day trial today and see how our platform can help you streamline your requirements gathering and management processes.
Don’t forget to share this post!
