ValGenesis Blog

Requirements Management 101: Tips for Writing Good Requirements

Written by Steve Thompson | Apr 26, 2023 2:46:37 PM

Have you ever added the wrong ingredient to a recipe and spoiled the dish? The same can happen when you are writing requirements. Requirements are a critical part of the requirements management process and the foundation of good software. They are the ingredients that make a system great.  

Writing good requirements is challenging; it requires skill and practice. However, it is a core competency for anyone tasked with writing test steps and test scripts and performing computer system validation (CSV) or computer software assurance (CSA). Validation tests a system to demonstrate it performs as intended, and intended performance is specified in requirements.  

In short, requirements are your future product, so getting them right, and documenting them early in your requirements management plan (RMP), is the key to better product quality, accelerated development, and less rework.

Using Agile in the Requirements Management Process 

In recent years, development teams have used the Agile methodology to simplify and refine requirements writing. This approach is seen as an improvement in the software development lifecycle (SDLC), replacing the traditional linear approach of the Waterfall methodology.  

Agile is an iterative practice; it breaks down large software development projects into smaller, more manageable tasks. Releases are more frequent, allowing users to see and contribute to the system as it’s being developed, as opposed to waiting months or years before actually being able to touch the system. The Agile approach promotes transparency and better communication and collaboration. It can help you translate user needs into well-defined requirements for a veritable product or system. 

Agile teams develop requirements and user stories, which are requirements expressed from the perspective of an end-user goal, in a more structured syntax. Here’s how requirements are decomposed in Agile: 

  • Epic  
    An epic is a large body of work that can be divided into smaller user stories that essentially describe what a customer (i.e., a user) wants. Epics can span sprints and even teams.  
     
  • User Story 
    “As a [persona], I want to [action] so that [outcome].”  
    Example of a simple user story construct: As a quality assurance professional, I want to review audit trails so that I can approve or reject items.
     
  • Requirement
    > URS (user requirement specification): already covered in the user stories 
    > FRS (functional requirement specification): elaborates upon user stories/user requirements 
    > DS (design specification): detailed requirements elaborated from functional requirements 

It is often difficult to distinguish “must-have” requirements from “nice-to-have” requirements. Here’s a tip: Writing requirements using must, shall, and should statement qualifiers can significantly help you manage and deliver a system that is compliant, fully functional, and even includes some nice-to-haves.  

8 Characteristics of a Good Requirement 

Aside from the structure and syntax of a user story, good requirements writing is a valuable skill to hone. Listed below are eight characteristics of a well-written requirement, as defined by The Institute of Electrical and Electronics Engineers (IEEE) Recommended Practice for Software Requirements Specifications, as well as examples of poorly written requirements and how to correct them. 

  1. Correct 

    Incorrect: “Validation status flag shall be green (HEX 00b300) to indicate every failed test step.” 

    Correct: “Validation status flag shall be red (HEX FF0000) to indicate every failed test step.”

  2. Unambiguous 

    Ambiguous: “Indicator for fail shall stand out.” 

    Unambiguous: “Validation status flag shall be red (HEX FF0000) to indicate every failed test step.”

  3. Complete 

    Incomplete: “Validation status flag shall be red.” 

    Complete: “Validation status flag shall be red (HEX FF0000) to indicate every failed test step.”

  4. Consistent

    Inconsistent: “All FAIL flags shall be orange.” 

    Consistent: “All FAIL flags shall be red (HEX FF0000).”

  5. Ranked for importance and/or stability

  6. Verifiable

    Unverifiable: “All FAIL flags shall be red.” 

    Verifiable: “All FAIL flags shall be red (HEX FF0000).”

  7. Modifiable (able to change the requirement)
  8. Traceable (able to uniquely identify and generate a traceability matrix) 

But there is something that has proven particularly useful in addition to IEEE’s recommendations, especially in highly regulated companies: using statement qualifiers.

Using "Must" as a Regulatory Requirement

When you elaborate on user stories, you end up in the traditional requirements elicitation and development realm — typically FRS and DS because URS is already addressed in the user story. The recommendation is to write your requirements using either must, shall, or should statement qualifiers, defined as:  

  • MUST: A regulatory requirement that is non-negotiable. The system must deliver upon this requirement; otherwise, you cannot release the system to production. 
  • SHALL: A business requirement that is required, but authorized decision-makers can negotiate these requirements based upon adverse impact to the business if not delivered. In other words, this is a risk-based decision. The system shall deliver upon this requirement unless the business decides otherwise. 
  • SHOULD: A nice-to-have that is not required. The system should deliver this requirement, but it is not necessary. 

Adhering to must, shall, and should requirement statements will allow you to read any requirement at any time and immediately understand its rank for importance and/or stability (i.e., characteristic #5 above). Furthermore, using statement qualifiers makes identifying the required rigor in testing easier. During audits and inspections, you will be able to quickly identify regulatory requirements versus those that are nice-to-have. 

There is another benefit. The word “must” will translate forward and backward in most languages without losing its meaning. “Shall” and “should” lose their meaning when translated forward and backward. This becomes more important with multi-national organizations or systems that span geographies. 

The Benefits of Digital Requirements Management

Improve and maintain traceability 

Advances in technology now allow us to manage requirements as records instead of documents. Managing requirements as records allows you to associate records (as in a relational data base management system or RDBMS), which, in turn, allows you to automate tasks like auto-generating the requirements traceability matrix (RTM).  

The RTM maps and traces the deliverables and test cases by establishing a thread for each requirement and test case from a project’s initiation to its completion. Some companies attempt to create the traceability matrix in Excel, which can be tricky and time-consuming. Unlike manual Excel spreadsheets, electronic RTMs in ValGenesis automatically update, show coverage, or lack thereof, and represent status in real time, including the impact of changes to requirements or test steps.  

Reduce effort and simplify compliance

The ValGenesis validation lifecycle management system (VLMS) also empowers users to manage requirements in a library of reusable objects (requirements, test steps, etc.). This expedites document development and delivers consistency because requirements can be assessed once and used by multiple systems. Consider 21 CFR Part 11 requirements consistent across all computerized systems where electronic records and electronic signatures (ER/ES) apply. Why not use the same requirements for all systems?

Align teams and activities

The newest ValGenesis release, VLMS 4.2, includes Design Manager, a purpose-built module that delivers agile, iterative SDLC functions but also allows users to manage more traditional requirements (URS, FRS, DS). It supports epics, user stories, and truly iterative, agile development with the ability to move requirements back and forth (to/from) the backlog and manage the development iterations in sprints. It’s an excellent tool for regulatory requirements management in the pharmaceutical and life sciences industry 

Design Manager also enables you to better manage software and system development initiatives because story points, which quantify development effort and time, can be controlled according to your unique organization, team, and environment. From story points, burndown can be tracked to ensure development is proceeding according to plan, and if it isn’t, you can correct the problem. Course correction is easier and more controlled due to Agile’s iterative nature and the ability to manage backlog.

CSV, CSA, Agile, and VLMS 4.2

ValGenesis VLMS 4.2 encapsulates CSV, CSA, and Agile, in addition to enhanced risk management features and functions. Requirements can be developed in the traditional way or using an Agile methodology. (This includes epics, user stories, story points, burndowns, and more.) 

Users can manage risk at the requirement record level, and the system can automatically apply a risk framework based on risk outcomes. This framework can dictate which testing types to perform, including the test modalities encouraged in CSA (ad hoc, unscripted, positive, negative, performance, security, boundary, scripted, white box, black box, and more).  

The point is that you now have options. You can continue to perform traditional CSV or adopt and perform CSA. You can develop requirements in the linear, sequential Waterfall approach or apply an iterative, agile SDLC methodology. It’s up to you to decide what is best for you, your organization, and your projects on a case-by-case basis.

Key Takeaways

Writing requirements is just one activity in the requirements management process, but it’s a critical one. Requirements that adhere to IEEE characteristics (consistent, verifiable, traceable, etc.), use statement qualifiers (must, shall, should), and are captured in a requirements management plan help ensure overall project success. Leveraging technology like the ValGenesis VLMS will further improve efficiency and effectiveness, including advances in validation methodologies (CSV vs. CSA) and SDLC practices (Waterfall vs. Agile).  

To learn more about how ValGenesis can bring increased efficiency and traceability to your requirements management process, contact us today.