{"id":21,"date":"2026-09-04T22:45:14","date_gmt":"2026-09-05T06:45:14","guid":{"rendered":"https:\/\/grumpyoldengineer.com\/?p=21"},"modified":"2026-09-04T23:21:54","modified_gmt":"2026-09-05T07:21:54","slug":"requirements","status":"publish","type":"post","link":"https:\/\/grumpyoldengineer.com\/?p=21","title":{"rendered":"Requirements"},"content":{"rendered":"\n
\n

I know that you believe that you understand what you think I said, but I am not sure you realize that what you heard is not what I meant \u2013 Anonymous<\/p>\n<\/blockquote>\n\n\n\n

\n

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.<\/p>\n\n\n\n

Structure<\/h2>\n\n\n\n

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.<\/p>\n\n\n

\n
\"\"<\/figure>\n<\/div>\n\n\n

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.<\/p>\n\n\n\n

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

\n
\"\"<\/figure>\n<\/div>\n\n\n

The structure and hierarchy depend on the system and the applicable regulatory standards. If it checks the boxes and the team isn\u2019t screaming, it\u2019s probably fine.<\/p>\n\n\n\n

In internal R&D, the focus often lands on the \u201clowest level\u201d requirements, with higher\u2011level ones backfilled later to satisfy process or regulatory paperwork. This is acceptable when risk is low. It is absolutely not<\/em> acceptable for a brand\u2011new system where nothing exists yet, unless you enjoy catastrophic surprises.<\/p>\n\n\n\n

Think of Requirements as a hub<\/h2>\n\n\n\n

Requirements will never contain all the details and edge cases needed to implement a system. They capture the WHAT<\/strong>, not the HOW<\/strong>, 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.<\/p>\n\n\n\n

Below is an diagram to illustrate requirements context.<\/p>\n\n\n

\n
\"\"<\/figure>\n<\/div>\n\n\n

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<\/p>\n\n\n\n

What vs How<\/h2>\n\n\n\n

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.<\/p>\n\n\n\n

Requirements should be at the level where design can occur. Then implementation follows design. The leading cause of hyper\u2011granular, unmaintainable requirements is teams who implement first (documenting in JIRA) and then reverse\u2011engineer \u201crequirements\u201d 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.<\/p>\n\n\n\n

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\u2019s not engineering, that\u2019s a cry for help. That’s almost as large as Trump’s One Big Beautiful Bill.<\/p>\n\n\n\n

Keeping requirements at the WHAT level is crucial. The only exception is when the HOW is explicitly a risk mitigation.<\/p>\n\n\n\n

Let’s assume we contracted out development work to two subcontractors A and B using the same set of requirements.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

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.<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

\n

Team<\/strong>: we don’t know what the requirements are because we haven’t done the solutioning yet.<\/p>\n\n\n\n

Me<\/strong>: please leave me the fuck alone…<\/p>\n<\/blockquote>\n\n\n\n

Side effect of HOW\u2011level requirements is requirements completion gets delayed until design is locked down. Worse if design is captured post\u2011implementation. Requirements will start changing every time design changes. This downwards dependency is not only wrong but also costly.<\/p>\n<\/div><\/div>\n\n\n\n

\n

Traceability is your friend, don’t abuse them<\/h2>\n\n\n\n

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.<\/p>\n\n\n\n

\n

Donut<\/strong>: you cannot do traceability without a tool like Jama or DOORS.<\/p>\n\n\n\n

Me<\/strong>: traceability is a concept you donut! How the hell do you think people did it decades ago before DOORS existed?<\/p>\n<\/blockquote>\n\n\n\n

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.<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

\n

Manager<\/strong>: leadership is asking for SE achievements past year, so I created a slide highlighting we created over 14000 traces in DOORS.<\/p>\n\n\n\n

Me<\/strong>: whatever’s wrong with you, it ain’t something small.<\/p>\n<\/blockquote>\n\n\n\n

Tools are great, but without understanding the \u201cwhy,\u201d they get misused. And misuse leads to maintenance nightmares.<\/p>\n\n\n\n

The worst abuse I see is tracing requirements to downstream free\u2011form 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.<\/p>\n\n\n\n

Do not trace requirements to headings, sentences, or paragraphs in free\u2011form design docs. Traceability works when items are atomic and standalone. If you try to trace a WHAT requirement into a sprawling design doc, you\u2019ll end up with traces scattered everywhere. Now imagine updating the design doc later. Enjoy your thousand broken traces.<\/p>\n\n\n\n

Closing Thoughts<\/h2>\n\n\n\n

Just don’t do stupid shit. Please.<\/p>\n<\/div><\/div>\n\n\n\n

<\/p>\n","protected":false},"excerpt":{"rendered":"

I know that you believe that you understand what you think I said, but I am not sure you realize that what you heard is not what I meant \u2013 Anonymous The biggest challenge with requirements is finding the right balance between academic purity, practical usability, appropriate granularity, and of course, timing. In other words: […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[6],"tags":[],"class_list":["post-21","post","type-post","status-publish","format-standard","hentry","category-requirements"],"_links":{"self":[{"href":"https:\/\/grumpyoldengineer.com\/index.php?rest_route=\/wp\/v2\/posts\/21","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/grumpyoldengineer.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/grumpyoldengineer.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/grumpyoldengineer.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/grumpyoldengineer.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=21"}],"version-history":[{"count":5,"href":"https:\/\/grumpyoldengineer.com\/index.php?rest_route=\/wp\/v2\/posts\/21\/revisions"}],"predecessor-version":[{"id":259,"href":"https:\/\/grumpyoldengineer.com\/index.php?rest_route=\/wp\/v2\/posts\/21\/revisions\/259"}],"wp:attachment":[{"href":"https:\/\/grumpyoldengineer.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=21"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/grumpyoldengineer.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=21"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/grumpyoldengineer.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=21"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}