The name SRS for a "software requirements specification" is well established and depending on how it's understood it could be written by the customer or written by the supplier. Colloquially, both "requirements" and "specification" are regularly used to refer to such document. It is similar to calling a document that describes test instructions either a "test specification" or a "test procedure" -- different people/projects/companies, different conventions.
What matters is to have a common understanding and work together.
Different terms for the same concepts. You could call it high- and low-level requirements, customer/supplier requirements or requirements and specification. While the form is important, a common understanding is core to be able to work together.
I agree, but I think one key distinction here is that I for my part tend to avoid classification. It's a spectrum of refinement, not two distinct classes IMHO.
The concept I use is that the next stage is all about how you implement the previous one: the spec is how you implement the requirements, the design is how you implement the spec, the code is how you implement the design.
As okl said, it’s arguably terminology, and maybe high and low level requirements would work for you? I prefer to separate out the terms though, so that “requirements” are the thing that the engineering team can’t unilaterally change without upsetting the stakeholders. If I can change a spec item mid-delivery and it doesn’t matter to the customer, then it wasn’t a requirement. If I can’t change it, then it’s a requirement.
Slight twist I learned from my wife: MoSCoW lists - Must, Should, Could, Won't.
The "Won't"s really tie down the boundaries of the system. If your PM is smart they probably won't call them "Won't"s, much more likely to bunch them into a column labelled "Phase 2".
As a systems engineer[1], I really appreciate that the author mentioned requirement prioritisation. Many requirements are contradictory, and it's all too easy and common for people to avoid conflict and just agree to a cop-out set of requirements such as the system being all of: feature packed, simple to use, able to be designed and implemented on a tight schedule, error free/secure, of high performance, etc. There's an entire comedy movie, Pentagon Wars[2], dedicated to this phenomenon.
There are a few other aspects of bad requirements that are particularly common:
* Requirements specifications created in absence of a software architecture. You end up with 2000 requirements all starting "SoftwareX shall ..." and then software developers assigned to individual components of the software are left guessing as to whether each requirement applies to their component. It's also much harder to make decisions like "that file export component of our software with 5 requirements... let's just use libxyz as-is rather than reinvent the wheel" vs. the same decision when considering 2000 requirements.
* Requirements without justification. The reason why a requirement exists is extremely important. If you want to change the requirement or have failed to meet it, you want to know the consequence and who you'd reach out to in order to advise of the change.
* Non verifiable requirements. Write down a few paragraphs of a test outline when writing requirements, not after the system is already designed (it's too late then). A bad requirement such as "SoftwareX shall have a simple user interface that is easy for newcomers to use" is meaningless during design and development and will get ignored. The threat of a planned verification method being "Bring 10 people of average computer literacy in a room and ask them without having used SoftwareX before to complete the following 10 tasks with SoftwareX in 1 hour. Pass if the average task completion rate is 80% or higher." will get designers and developers thinking.
* Not using exemplars, images, videos, etc in requirements. Good requirements may be as simple as observing that SoftwareY is pretty good for certain aspects, and should be a source of inspiration. Or "Watch this video of SoftwareZ in action, this is what we want our software to do as well."
As a couple others have commented, this post seems a little muddled, and there is a huge formal set of work in the world dealing with what Requirements are, how to elicit them, and then work on design. For example, see the INCOSE Requirements Working Group [0], and their Guide to Writing Requirements [1].
It’s key to remember that the requirements of a Thing are the WHAT and not the HOW. Keep the requirements separate from the Design, then the requirements can stay pretty short and sweet.
It takes a very specific type of engineer or analyst to be able to think at this level of abstraction and not jump into solutionineering (design) when trying to establish exactly what the stakeholders want the system to do.
Spot on regards the what and the how. Additionally to specify the what, i always document the rationale WHY. We can see this in sentence patterns for specifying use cases, epics, etc.
I'm not sure if it's unique to my place of work but most requirements are made up. If something is or isn't implemented in the final solution has no real bearing on happiness. The thing that everyone seems to be after is a well thought out solution with empathy for the users. Strict requirements get in the way of that in my experience.
Requirements serve to define the goal/agree on what's in what's out. If that can't be spelled out in sufficient detail (regardless of form), production shouldn't begin - make a prototype (or something else that helps define the work to be done)
Coming from the Controls Systems Industry, I have seen a few flavors of the SRS. Sometimes we call them Functional Requirements Specifications (FRS). The IEEE has a decent standard for how to put one together, although they call it Software Design Description, "IEEE 1016-2009 IEEE Standard for Information Technology--Systems Design--Software Design Descriptions."
The two industries where I worked where these are well recognized and their use enforced are Nuclear Power and Pharmaceuticals.
Some personal wisdom that I picked up is "If it can't be verified, it isn't a requirement." As an example, I was one told to change the tagnames in a program to "something meaningful." I went through several iterations before I realized that, with this particular customer, that was unachievable. None of the tagnames I built had meaning to him, and he would not give me guidance as to what would be better.
Great article that I would have loved to have read 5 years ago. I work in med tech and have to develop software according to the IEC 62304 standard. I was responsible for designing our software development process and when reading the standard I had no idea what these concepts (requirements, traceability, etc) meant in practice. Initially I thought these were outdated concepts (the standard was written in 2006 and now everyone is cool and agile). However, after dozens of releases and team composition changing all the timeI definitely see the value in theory. In practice many companies have bad requirements and no proper requirements management systems, so for them the standard is probably more of a burden.
Anyway, would have loved to read this much more positive view of requirements systems before, so I would have tried to build something beautiful instead of shoehorning the IEC standard into our existing process.
A pity. For me the IEC 62304 is one of the standards who make the most sense.
For me traceability has one more very nice aspect: you always trace whatever you do (think merge request or it deployment request / changes) back to the reason/authorization why you do it (think project, change request, defect, ...). Like that you are never in the limbo why you do something. Especially in regularity domains that is a must have but honestly i would not run a company otherwise. Because it also ensures that money is spent where you want it. With or without requirements in between them.
The article focuses more on requirements but I think that traceability is at least equally important -- Why (what is the justification) to include feature X (in this way)? If this is disregarded it becomes difficult to work economically towards a goal. Unfortunately, it is often the way things are done because a) people want to satisfy their curiosity and "play" around with new things (which is fine if kept in check), b) problems are complex or poorly understood and doing something is easier than finding out.
Great read, I spent years thinking requirements should live somewhere like Jira, and I feel for many teams this is the case.
But as the author mentions, Jira contains tasks related to bugs, text changes, colour changes etc.. These are not product requirements per se.
Like the author, I came to the conclusion requirements are best kept in a requirements management system, that integrates with your project management tools - a source of truth and living documentation about what the product does. (Not conversations back-and-fourth about bugs and UI minutia).
And like the author, I have also created a requirements management system https://userdoc.fyi (currently we are specifically focused on user stories, personas, and journeys).
In formal systems engineering, a common mistake (including for the 737MAX[1]) is failing to model system users, and treating system users as completely external and separate to what is being designed.
I'd love to play with an Inform 7[2] like language for capturing "operational scenarios"[3] (systems engineering jargon for roughly a combination of "personas" and "journeys"). In many fields of systems engineering (e.g. aviation), vocabulary has to be tightly controlled and syntactically unambiguous language used. As is the case with Userdoc, an LLM could propose operational scenarios, but they'd need to be converted to a syntactically unambiguous language, and be vetted by humans. Of current approaches to formally capturing operational scenarios, and I don't think any of these do a particularly good job of it, I prefer Object Process Methodology[4] (text representation only) over SysMLv2[5] (again text representation only, and this is R&D/draft). I'd only mention SysMLv1 or UML use cases as something I'd forever avoid.
Correct. The big fallacy of agility. Mixing work items with requirements (words like feature or user story are terrible abused here). If you need a specification in an agile project, then it is an output of the work items next to the code.
Correct, you can create requirements anywhere, I just feel requirements are more important, and long-lived than a transitory Jira ticket.
E.g. A Jira ticket moves to "Done", the requirement is complete, and people are happy. But the important info on that ticket has essentially disappeared - obviously you can mine your thousands of tickets for historical info - but no one really does.. as it's mixed with bugs, changes, improvements, conversations etc.
I don't know how exactly you'd do that and depending on the project it might be fine.
One important feature of a requirements tool is that it allows you to "tag" a set/document of requirements with a version that corresponds to your released artifacts and create "diffs" between such versions. I don't think that's possible with plain Jira(?)
Maybe I've only worked in ass-backwards companies but it seems to me that for almost all stakeholders, including project managers, bosses and clients, the "requirement" abstraction really does mean:
> [This feature is] something that absolutely must be in the next release of the product
All this thinking is well and good for figuring out the implementation side of that abstraction. But all this thinking won't get you off the hook when you "fail to deliver." At the end of the day, the meaning of "fail", "deliver" and "requirements" is usually not up to you.
If you don't know who Gerry Weinberg is, then look that up too. You will profit from the exercise.
1. https://geraldmweinberg.com/Site/Exploring_Requirements.html