Every employee wants their teammates to value their contributions. This is a universal desire. In this article I will describe how to contribute effectively to a specific kind of project that I know: the software requirements specification.

Specifically I will describe how to help craft this document as a Quality representative on the project team. The Internet abounds with resources on everything software-related. So in this article I hope to convey my own unique experience and voice on this topic. If you have ever been the Quality representative on any kind of software team, I invite you to read on.

What is a software requirements specification?

The software requirements specification (SRS) is an important document in software development. It is crafted near the beginning of a software development project. Its structure includes:

• A complete description of the software’s function
• Defining, in advance, how users will use the software
• Defining all quality and engineering requirements and applicable standards
• And others

Here is a good definition from Wikipedia: “Software requirements specification is a rigorous assessment of requirements before the more specific system design stages, and its goal is to reduce later redesign.”

Its purpose is to:

• Prevent failure
• Reduce redesign
• Meet and exceed requirements

The SRS is important because it helps prevent project failure. Simply put, it is useful. A well-crafted one will save time and money during development and serve as the basis for verification and validation later on.

Behind the SRS is a complex process of requirements elicitation, made possible through effective communication and documentation. The person who writes it is generally a business analyst. This individual is not a developer, not a user and not a manager, but someone trained in the software lifecycle and in technical writing.

Where Quality fits into this effort

The SRS is fundamentally a Quality process, even though it is not driven by the Quality unit of the company.

Note the terms requirements elicitation, verification, validation, redesign, standards, etc. The SRS is a quality planning document, with the intent of building quality into the software instead of reworking it toward the end of the project. It is a tool for establishing explicit, agreed-upon standards by which to judge the outcome (which parallels the Quality unit’s role of checking). It prevents redesign, which is analogous to scrap but is probably even more labor-intensive to address.

In addition, the Quality unit may be an internal customer that will use the software. As a representative on the team you thus help to provide user stories and convey what is important to you in using the planned software to do your job.

All engineering involves trade-offs. The information you provide, once it is explicitly documented in the SRS, helps the software engineers to prioritize wants and needs and incorporate them into the final product.

My own experience

I had a great opportunity to be on such a team. The goal was very worthy: to overhaul our clients’ ordering process.

Leaders within my company had heard client feedback about our ordering process and not all of it was positive. In addition they had their own experience to draw on: they compared our clunky, web-based form with the frictionless experience of ordering on Amazon.com or other e-commerce apps. They compared them and realized we could do better. If we redesigned our ordering system to be like Amazon’s, our clients would avoid the occasional frustrations, would be more likely to come back, and would be more likely to order the additional testing and manufacturing services that we recommend.

I joined this team after the initial project charter was created but before the SRS was created. The charter reflected these worthy goals and it had inspiring language created by the project manager. The charter also conveyed the full support of executives (including the “project champion” from the executive leadership).

Once my name was added to the charter and my responsibilities listed, I felt eager to contribute toward making the project a success. Helping with the SRS is one of the ways I did so.

Key components of an SRS and my own experience

In general an SRS will contain the following:

1. Purpose

2. Scope

3. System overview

4. References

5. Definitions

6. Use cases (user stories)

7. Functional requirements

8. Non-functional requirements

I won’t go into detail because you are quite capable of Googling this stuff. But I would like to highlight the Quality unit’s role in the SRS’s purpose, use cases (user stories), and functional and non-functional requirements sections.

The Purpose section of the SRS is worth your attention. You should scrutinize it (and the project charter) to understand the goals of the software and how you will use it.

In my case (the client ordering system I mentioned above), I would use the client information entered in this new ordering system during my reviews and audits. Therefore it was very important that the project team incorporated my Quality input on regulations regarding handling and reporting of client-provided information.

For instance, the proposed system needed to preserve client-provided sample names, lot numbers, surface areas, extraction ratios, preparation instructions, etc. with exact fidelity. In the event of a change to this client-provided information, Quality would need to review each change. Each change also needed to be attributable and time-stamped in order for the Quality unit to meet its Food and Drug Administration-mandated objective of reviewing these changes.

The Use cases (user stories) is where Quality (and other future users) convey to the team how they will interact with the software.

In my project, the most important user of the client ordering system is the client. The project team I worked with had extensive communication with several of our clients who had expressed willingness to “pilot” the new system once it was online. These were loyal clients who had mastered the old system and all its kinks, but were eager to use a new and improved one.

In addition to the client, Quality would interface with this system daily and hourly when reviewing reports, inspecting manufacturing processes, and inspecting in-process scientific studies. We would also pull up this client order record during audits, during failure investigations, and before approving reports and certificates. As Quality representative, I and another auditor collaborated and described to the team how we would use the new software. With the business analyst’s help, these user stories were formalized and refined and they became part of the SRS.

Lastly, the functional and non-functional requirements sections help project stakeholders understand and agree on what the software will do and how it will work. In software engineering there is a distinction between the two kinds of requirements. You don’t need to understand this distinction or separate your input into the two categories. More important as a Quality representative is to communicate on an ongoing basis with the team to convey your must-haves and your wants. You will commit to being a good-faith negotiator on needs versus wants. You will make a full effort to understand, and then you will be flexible on your wants but clear on your needs.

Here are some examples. In my project to create a new client ordering system, the following requirements surfaced:

• The ordering system must communicate with full fidelity/exactitude with our Laboratory Information Management System (which is used in data capture and reporting).
• The system must have full audit trails, allowing investigations to capture the who, what and when of every change to client-supplied information.
• The system should flag any changes to client-supplied information made by company technicians and scientists after the sample submission with strikethrough text or an asterisk, to allow the Quality unit to review these changes.
• The system should allow Quality to pull up a few useful reports, including a report for inspections of ongoing studies, and a report to pull up during client visits.
• The system should be clear about where the definitive record is, so that there is no disagreement or confusion for a reviewer contemporaneously or months or years down the line.

The examples above are both functional requirements and non-functional requirements (in software engineering terms). They are also divided into wants and needs. In this project I was explicit with the team about the audit trail need because regulations require that the Quality unit review changes to critical study data. We needed to ensure that a sample submitted under one name would not be reported under another name, without the proper authorization and review.

When it came to “flagging” these changes, I considered such a feature a want because such system flags would help us zoom in more efficiently on changes, deletions and insertions that needed Quality review. In discussions with the team my Quality partner and I made it clear that this and the reporting features were a couple of “nice-to-haves” so that the team could prioritize while still understanding our desires.

The last bullet point is borderline between wants and needs. On one hand, computerized systems that talk to each other are bound to have redundant data. Written procedures can compensate for this by pointing to the most concise record. On the other hand, any hint of contradiction in two computerized systems could be problematic if regulators examine the record years later and cannot reconstruct what was actually done in the lab or manufacturing area.

There is one last SRS component I would like to highlight: diagrams and pictures.

Busy people (doesn’t that include all of us?) and adult learners in general will scan the document for images. If you can create a Microsoft Visio process chart that illustrates clearly and simply how Quality will use the software, then this image may feature prominently in the SRS, and it will help the team and others in your company to understand your role and build software that will fully equip and enable that function.

Microsoft Visio is a fantastic tool that warrants an article of its own. (Alexa: remind me in 3 months to write it!). If you use Visio to map out the Quality interface with the planned software, review this diagram with the technical writer and your unit, make it pretty and then finalize it in a way people can agree on, you will be a hero. And your work will feature prominently in the SRS.

How to contribute as Quality representative

Help the software team out at this crucial stage by being available, by reading the project updates thoroughly, by relaying needed info back to the Quality team (while cc’ing the project manager and observing any other project confidentiality ground rules), and by bringing questions you can’t answer to Quality management.

Below is a list of further tips:

• As a Quality representative you can help the writer of the SRS to fully describe:
  • System Interfaces
  • User Interfaces
  • Hardware Interfaces
  • Software Interfaces
  • Communication Interfaces
  • User characteristics
  • Reliability
  • Availability

For instance, you will learn how the proposed software interfaces with your already-existing systems. You will convey to them how often and where you will log in (at your desk, in the labs, on the manufacturing floor, on a portable tablet, etc.). You will be able to request reviewer-only access, or superuser or Quality administrator privileges for your group.

You may convey to the writer of the SRS how the typical Quality employee goes about their job. Are they all tech-savvy? Will they know how to use a tablet or stylus? Are they accustomed to pulling up the proposed reports and queries?

You may need to convey how and where Quality auditors and specialists do their jobs. If the software needs to be accessed while in labs or on the manufacturing floor, it might require a tablet. Will the WiFi connection be fast enough? Will the tablet be durable? Will it be wheeled about on a cart, or carried by hand? Will it be navigable and reliable if a client wants to see the system? Or does it require an employee to print out a manual copy of a report for the client to review?

• To continue in this vein, the Quality representative may contribute quality attribute general scenarios:
  • A modifiability general scenario
  • A performance general scenario
  • A availability general scenario
  • A security general scenario
  • A usability general scenario
  • A reliability general scenario

Don’t be intimidated by the term “quality attribute general scenarios.” You are not responsible for putting Quality requirements into engineering terms that will be used by developers. Rather what this means is that the Quality representatives will convey system-independent requirements, and the writer of the SRS will draft them into system requirements.

As an example, Quality may require that auditors have read-only access to the system, so that they fulfill their role of checking but not altering or “fixing” things themselves, which would muddy the waters of measurement and accountability. This is a system-independent requirement. The writer of the SRS will convey this requirement into technical terms and it will thereby become an architectural pattern and a set of measurable, specific quality attribute requirements. See the Carnegie Mellon University link below for an interesting discussion of these terms.

Five final tips

Consult with your team for additional perspectives. Explain the goal of the project, and then provide specifics. Give an open invitation to join for those who want a greater voice in a software project that will affect them.

Escalate to Quality management if you encounter a question that you don’t know the answer to. Consult Regulatory for requirements you may not be aware of that may need to be reflected in software requirements. Ask a manager to help you distinguish between wants and needs. Ask a manager to join you in project meetings if you need to press a certain point more finely.

Read the project charter in the beginning and re-read it occasionally or when it is amended. Share it with the Quality unit if it will help them understand the goals and benefits of the project.

There are development methodologies where an SRS is not central. Consider the following forum response (I edited for clarity) from https://cofounderslab.com/discuss/are-spec-documents-still-necessary-for-software-development. The author is referencing the fact that you can’t know everything in advance, no matter how much you plan:

“Recently developers have articulated why Big Up-Front Design (BUFD) is the hallmark of failure. BUFD is typically an exercise in make-believe, where you pretend you fully understand the problem and how precise code will solve it before you even begin development. The design document is treated as a contract, and all kinds of pain ensues. Been there, done that.”

This means you should be open to other, novel means of capturing requirements. You should be as agile as the rest of the team!

Lastly, various companies will try to sell you software to create SRS’s. Some of these services may work great. However a vendor cannot do the hard work of talking to people, following through, clarifying, etc. A senior product manager at Cisco said, “Understanding what is actually required is both a science and an art.” (See the smartsheet.com reference below). A piece of software on its own cannot achieve one of the main objectives of the SRS, which is to foster consensus. Do a CTRL+F on my article and note how many times I used the word “craft.” A skilled communicator often drives the SRS process and makes it so valuable to the software project. You can make this person’s job easier through your contributions.

Research further on your own with these resources

SRS templates:

• Your company may have a preferred template. You may use an IEEE-based one or a variation on the following:
• https://www.e-education.psu.edu/geog468/sites/www.e-education.psu.edu.geog468/files/Geog_468_Project_Template.docx
• https://www.uccs.edu/Documents/tboult/srs.doc

Examples of actual or mock SRS’s:

• http://www.cse.chalmers.se/~feldt/courses/reqeng/examples/srs_example_2010_group2.pdf
• http://cci.drexel.edu/seniordesign/2016_2017/Als/ConnectomeSRS.pdf
• When you search for SRS templates or examples, I recommend using the search engine tactic of asking for .edu sites only. Example search text: “software requirements specification example site:.edu”

YouTube videos:

• Some YouTube videos on SRS’s are of poor quality or are simply incorrect. Some are from third-party companies that want to convince you that their software/outsourcing operation is the only way to do it correctly. I won’t provide a list of videos because the assortment is constantly evolving. Since you are a Quality professional, I trust you to use your well-practiced discernment!

Articles and papers:

• https://www.smartsheet.com/software-requirements-specification-101
• https://www.onedesk.com/writing-a-software-requirements-specification-document/
• https://belitsoft.com/php-development-services/software-requirements-specification-helps-protect-it-projects-failure
• https://www.geeksforgeeks.org/how-to-write-a-good-srs-for-your-project/
• https://www.bmc.com/blogs/software-requirements-specification-how-to-write-srs-with-examples/
• https://microtoolsinc.com/papers/how-srs/
• https://www.ou.nl/documents/40554/349790/IM0203_02.pdf
• https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=513803

Final thought

I see a bright future for individuals in Quality who are able to interface effectively with software teams. If you can communicate with business analysts and developers and bring that technology back to your Quality unit, you will benefit both groups and you will grow in credibility and prestige.

I hope you have felt a spark from reading this article. I enjoyed writing it. If you have a question or comment for me, let me know below!

p.s. The photo is from Saint Johns Bridge in Portland, Oregon. I took it on a fine sunny day in Cathedral Park.