Next Mile and Space Cowboy have collaborated on a four-part series about requirements. This article, part 1, answers “what are requirements, anyway?”

Requirements document what the software or hardware implementation team plans to do. Requirements specify why a given product or feature should be built, what it must achieve, and how the implementers know they’ve succeeded. Business analysts elicit requirements from business, customer, and technical contributors, then synthesize and document them for project implementers, testers, and supporting stakeholders.

Functionally, proper requirements act like an insurance policy against the downsides of humans’ instinctual selection and action biases. Engineering quickly becomes involved enough that implementers will forget details along the way, and requirements can refresh participants’ memory as they switch from one task to the next. Done right, requirements guide the project in the correct general direction. Done wrong, they risk becoming an anchor instead of a keystone.

While requirements may sound boringly simple, we can assure you that requirements are just boring. In what other contexts do you hear about something being required? Nowhere fun:

• Proof of insurance required
• Photo ID required
• Shirt and/or shoes required

So, dealing with the state, canceling your Verizon service, or being kicked out of the convenience store (again). Even in technology, requirements exude an unpleasant mandatoryness—the Happy Hour with Coworkers! part of the project.

When invoked, “requirements” becomes the organization’s euphemism for the project’s “getting our shit together before we spend a boatload of money” resolve-building phase. Requirements are the first place business stakeholders and technology implementers agree on what should happen. Without them, you build on whims: what was needed that day, that hour, or to douse that fire and make progress.

That making progress will always trump hitting the target, so requirements help mitigate the negative consequences of day-to-day action bias, sunk cost bias, and ambiguity aversion.

Intuitively, requirements should be hard, fast, unchanging, and clear. However, the ironic truth/punchline is that in their quest to clarify, requirements risk becoming the very turbid confusion or irrelevance they’re written to solve. How does this happen so readily?

Weak starts. For implementation staff, requirements always begin on the wrong foot. As the most poorly-advocated-for subdiscipline in software and hardware engineering, business analysts and their requirements often feel like an early-stage blocker at best, masturbatory time-waster at worst.

Inconsiderate rhetoric. It's ridiculously easy to find a requirements template online, impress the business stakeholders, and assume you killed it. However, it’s unlikely your template harmonizes with the mental model of the implementation team who will find it confusing, impenetrable, and ultimately useless. BAs interface with the business a lot, and parroting them can feel like success, but we need to write for the engineers who are writing the code and testing it.

Performative certainty. Business stakeholders routinely mishandle non-engineering functions and requirements are no different. Most see requirements work like an arcane religious tradition, the rites and sacraments of which everyone follows but no one understands. Requirements are a box that must be checked, and once checked, instantaneously forgotten in favor of “the real work”. Still, we’re often stunned to find that business stakeholders don't read the requirements, even when asked. One of the dirtier jobs a BA sometimes undertakes is to make requirements palatable and shove them in peoples’ faces to surface disagreement.

Requirements themselves. Worse, requirements aren’t hard or fast, either. They’re just like glass: slow, liquid, brittle, impure, and never perfectly clear. Objectively irredeemable, but the right tool for many jobs. Teams get into trouble seeing “The Requirements” as a holy text that can't be adjusted to account for what we learn and changes in our reality. Requirements go wrong when they stop painting a clear-enough picture of our desired outcome. Good enough is negotiable, perfection is not.

Writers’ delusion. Welcome to metarequirements, where technical writers pen their own user story!

“As a technical writer, I dream of creating a monolith of documentation that will inflate the consciousness of any who dare click on its hyperlinks.”

Related to that over-confident tech writer is the imposter syndrome tech writer. Their show of effort has a similar outcome: an impenetrable, pointless wall of self-outdating requirements content.

While the risk from avoiding requirements may seem clear now, there’s nearly equal risk in writing them. Said risk doesn’t come from requirements being bad or wrong, but from requirements becoming uncurated.

Left unmanaged, requirements regress to chronicling the whole program, like a mirror reflecting its unfiltered visage. Every whispered constraint, hoped-for adjustment, alternative fact, and on-again/off-again need lives in the same archive alongside what you actually did and need to do. Trouble is, as a project progresses, things change:

• We learn more about our capabilities and constraints.
• We learn more about the expectations and needs of our stakeholders and users.

As external factors shift during development, project goals may change accordingly. A requirements document’s users need only what they need, and their need for brevity increases with any change.

Further, Agile management methods have also prioritized delivering value in bits and pieces over time rather than all at once at the end of a project. Authors’ audiences only really need the requirements that are relevant to what we are doing right now. (It also means we’ll lose sight of our objective as we iterate.)

When requirements contain audience-irrelevant content, their authors erect a barrier that imposes intellectual labor better spent elsewhere. While the fruits of said requirements work may be sweet as a Fuji apple, if they’re mixed in with both the rotten apples and the other fruits, your reader will trash the whole vile salad.

If you’re drafting hardware or software program requirements, don’t overfocus on the output. In most cases with most teams, it’s your collaborative, facilitated act of defining that matters, not the definition. The collective thought process and the resultant pseudoconsensus helps you mix steps forward into a project’s natural steps backwards and sideways. To succeed, focus on relevance, timing, and context sensitivity.

Relevance required

One of the first examples of "the requirements" we’d ever seen was a twenty-page outline. All text. For a mobile app. Naturally, the text did not reconcile with the visualized user experience. A collaborative story mapping session can help in this kind of situation to organize atomic requirements in terms of the user experience.

A good place to start is often with the intended audience. For a different mobile app, the BA team asked the implementation team what they wanted to see in requirements documentation. The response was simple and clear:

“We just need to know what a user should be able to do on any given screen.”

This simple approach, identifying the screen as the organizing principle, made ingesting requirements information feel natural for the implementation team. What are the fundamental elements? For an interactive application, this will usually include content, data, and actions. For each screen:

• What are the static elements?
• What’s data driven?
• What’s interactive?
• What’s the outcome for each user action?

Your requirements documentation can also include links to any design files, but don’t include the design files themselves since those could change. Interestingly, most design changes will not alter the details of a given interface as described in the structure above, but they may require you to add or delete functional content. Still, we recommend reviewing designs shortly before development.

Timing required

When you call an airline, or your cable company, the automated voice prompts and the menu structure are provided by an Interactive Voice Response, or IVR. Like other interfaces, the IVR can be defined in terms of a navigation structure and the options available at each node. The IVR can also accept input from the user and communicate with other systems to perform its job.

Unlike most software, our team and the implementer had to nail down every detail of the IVR before it could be implemented. You’d think that means the requirements author should work months ahead of the implementers, but running too far ahead and getting too distant from the experts will make your whole plan unravel like ours did. Requirements often depend on unstated assumptions that will be invalidated by the implementation team. Pre-work is re-work. Find and maintain the correct gap for your team’s workflow.

Sensitivity required

In conversation with other BAs about the correct level of detail to include in requirements, several factors became evident:

1. The level of domain knowledge of the implementation team. Less knowledge requires more context.
2. The level of technical knowledge of the implementation team. Less knowledge requires more detail.
3. The confidence level (or psychological safety level) of the implementation team. Less confidence requires smaller steps.

Importantly, additional context can be documentation separate from the requirements such as use-cases, diagrams, decks, etc. As long as they’re appropriately relevant, properly timed, accessible, and communicated unambiguously, this’ll work fine. Your primary requirements document doesn’t need to contain every bit of context.

Ultimately, useful requirements match the way people learn. Thinking takes energy, so humans form a generality first, then look for specifics that support it. They do so in chunks to avoid information overload (wasted time/energy).

Paradoxically, overdescription reduces clarity, increasing the chances of misinterpretation. Overdescription manifests to its readers as implementation how-tos (“tell me how to do my job…”), excessive context, blurred lines with other work, hyper-specific test cases, or finalized APIs or UIs, all of which can now be summarily dismissed as a whole if one small detail’s off.

Technical writers must deliver requirements using the minimum effective dose: communicate what’s necessary to build today and not a shred more. A requirements digest, of sorts. More on that to come.

---

Space Cowboy and Next Mile make requirements effective. Reach out to us for software and hardware requirements that make your project more efficient.