The biggest challenge with requirements is finding the right balance between academic purity, practical usability, appropriate granularity, and of course, timing. In other words: trying to satisfy four competing masters while everyone around you insists their favorite one is the only one that matters.

Structure

There are countless ways to structure requirements, and every team swears their way is the “one true way”. In reality, the structure should be whatever actually works for the team and the system of interest (within the limits of your standard operating procedure). Despite the endless debates, the core structure across organizations is shockingly similar.

All requirements start somewhere. It may be provided by the customer or by an internal team. These requirements are then decomposed to a level where engineering can start development or make a decision on whether to make, reuse, or buy.

That latter path is mostly relevant in formal contractual environments, the kind where the system is large, complex, and terrifyingly high‑risk because half the capabilities have never existed before. In internal R&D, where you’re iterating on an existing product, that level of overhead is usually unnecessary. Below are examples of how requirements can be structured.

The structure and hierarchy depend on the system and the applicable regulatory standards. If it checks the boxes and the team isn’t screaming, it’s probably fine.

In internal R&D, the focus often lands on the “lowest level” requirements, with higher‑level ones backfilled later to satisfy process or regulatory paperwork. This is acceptable when risk is low. It is absolutely not acceptable for a brand‑new system where nothing exists yet, unless you enjoy catastrophic surprises.

Think of Requirements as a hub

Requirements will never contain all the details and edge cases needed to implement a system. They capture the WHAT, not the HOW, because, newsflash, the system doesn’t have a solution and hasn’t been built yet. This surprisingly is a very difficult concept to get through some people’s thick head.

Below is an diagram to illustrate requirements context.

What requirement enables is a navigable pathway between system elements, capturing the decomposition trace, justification, and how we got to a certain point. For example, I may navigate from a risk to the associated requirement, the design, and how it’s being verified. Note, the child owns the trace. Always

What vs How

One phrase I keep hearing (and which I immediately correct) is “requirement needs to be at the level which developers can code to”. This is just total horse shit and the person repeating this should be escorted out of the building.

Requirements should be at the level where design can occur. Then implementation follows design. The leading cause of hyper‑granular, unmaintainable requirements is teams who implement first (documenting in JIRA) and then reverse‑engineer “requirements” from whatever they just built. This guarantees a future of pain, because the WHAT becomes dependent on the HOW, a dependency inversion that should make any systems engineer break out in hives.

I once saw a software requirements spec exceed 700 pages for a standalone mobile app. Seven. Fucking. Hundred. Pages for a standalone phone app. That’s not engineering, that’s a cry for help. That’s almost as large as Trump’s One Big Beautiful Bill.

Keeping requirements at the WHAT level is crucial. The only exception is when the HOW is explicitly a risk mitigation.

Let’s assume we contracted out development work to two subcontractors A and B using the same set of requirements.

In the above scenario, we would get two different design and implementation from each subcontractor that would still meet the requirements. If we wanted more granularity and control, we contract out with the design spec; this will get us two different subcontractor implementations.

Keeping the requirements at the “WHAT” level provides flexibility to the Lead Systems Integrator. For example, if one SW subcontractor is “not working out”, we can switch to a different SW subcontractor. While this can get complicated in reality, the requirements methodology supports it.

Team: we don’t know what the requirements are because we haven’t done the solutioning yet.

Me: please leave me the fuck alone…

Side effect of HOW‑level requirements is requirements completion gets delayed until design is locked down. Worse if design is captured post‑implementation. Requirements will start changing every time design changes. This downwards dependency is not only wrong but also costly.

Traceability is your friend, don’t abuse them

Traceability is essentially the integrity of the system. You can tell a lot about the project and team just by looking at their traceability structure.

Donut: you cannot do traceability without a tool like Jama or DOORS.

Me: traceability is a concept you donut! How the hell do you think people did it decades ago before DOORS existed?

Traceability is a concept of going from A to B in a uniquely identifiable way. First thing is to understand why we need it (besides process and regulations) and how we’re going to implement it in the most practical way. Once this is understood, we leverage tools like DOORS and Jama to help us execute.

Traceability is simply the ability to go from A to B in a uniquely identifiable way. First understand why you need it (besides process and regulations), then figure out the most practical way to implement it. Tools like DOORS and Jama help execute, they don’t define the concept.

Manager: leadership is asking for SE achievements past year, so I created a slide highlighting we created over 14000 traces in DOORS.

Me: whatever’s wrong with you, it ain’t something small.

Tools are great, but without understanding the “why,” they get misused. And misuse leads to maintenance nightmares.

The worst abuse I see is tracing requirements to downstream free‑form design documents. People are now stuffing entire documents into requirements tools and tracing them to requirements. This happens because tool vendors love showing off shiny (useless) features, and organizations behave like kids in a candy store.

Do not trace requirements to headings, sentences, or paragraphs in free‑form design docs. Traceability works when items are atomic and standalone. If you try to trace a WHAT requirement into a sprawling design doc, you’ll end up with traces scattered everywhere. Now imagine updating the design doc later. Enjoy your thousand broken traces.

Closing Thoughts

Just don’t do stupid shit. Please.