How to Write Requirements So Your Engineers Don't Hate You

Writing requirements is more of an art than a science. But this oft-overlooked skill can be the difference between a project succeeding on time, on budget, and with actual impact, versus a project that lives in perpetual chaos and fizzles out because nobody really knows what anybody else is doing. And writing requirements is not cool. It is not sexy. It is a soft(ish?) skill in a world dominated by hard-skilled engineers who can't be bothered with such frivolities.

I have seen plenty of requirements that look like this: "Send an email to the user when they add product A to their existing product B subscription." Then the PMs brush off their fleece vests, close their laptops, and head to kombucha happy hour trivia, only for engineers to grumpily respond that this requirement is bad. Or worse, and perhaps more common, nobody says anything, and the project stalls until implementation starts or someone realizes the requirement is impossible to meet.

So let's unpack the requirements writing process. On the surface, the example above sounds like an easy requirement to meet, right? What is so hard about sending an email?

Half-Baked Requirements

Firstly, the copy of the email is not addressed. Do you really want engineers writing that? Not really. You are going to need to provide copy, a proof, and a wireframe. Possibly internationalization too, if you do not already have a solution for that. Also, what links should be in the email? Do those links need to be pre-signed, private, or something else? Is delivery legally required, and does that imply data audit or storage requirements?

The requirement also says "send an email," but how quickly does it need to be sent? One second? One minute? One week? Each of these options has different engineering implications. Ultra low latency likely needs to live in the "hot path" of a customer facing flow, which introduces reliability and stability concerns. Longer latency might be handled through a fire-and-forget event pipeline (assuming one exists). Even longer latency could be handled through a batch job. All of these decisions have technical costs, tradeoffs, and implications on the current status quo of the rest of company operations. A good requirement considers these. You shouldn't "require" one second latency if there is no meaningful customer difference between one second and one minute, especially when that one second latency might have 10x the implementation cost. It can be difficult to estimate implementation cost as a non-engineer, but at minimum, you should at least be aware that tradeoffs exist and do your due diligence in evaluating the customer-side impact.

Finally, the requirement mentions sending users information about product A when they add product B, but it doesn't mention (or at least demonstrate awareness of) potential implications to existing product A flows. Do we need to modify emails for product A to now be aware of product B? Is that even possible given the mechanisms for sending product A emails? Are there edge cases (such as a user with product B but no product A) that we need to account for? That might not be reflected in the requirement, but it can easily become a major downstream problem.

What am I Missing?

So right away, we have uncovered a few issues with our "simple" requirement that's starting to look not so simple after all:

• Incomplete requirements: No copy, no templates, no wireframes.
• Lack of specificity: No latency requirements or tradeoffs mentioned.
• Missing data investigation: Is the data needed to determine whether a user has product A available at the point where product B is added or renewed?
• No status quo analysis: What happens to existing flows if this new path is introduced?
• Ownership gaps: Who owns and maintains these new customer communications?

This list isn't exhaustive, of course. An exhaustive list will vary from project to project and company to company. But these are exactly the kinds of questions that go unanswered and quietly fall through the gaps. If you have ever wondered why a project is rife with chaos and never quite gets delivered, it is usually because the answers to these questions are being made up on the fly, neglected entirely, or discovered too late and force a painful revisit of designs and estimates.

Are requirements the root of all evil? Maybe. But something something about necessary evils and all that.

Writing a Better Requirement

There is no secret, 100% correct formula for writing requirements that magically answers every issue that will come up. There are plenty of helpful guides, but a definitive answer simply does not exist.

Our example above has the "what." But it is missing the "why" and the "how."

Let's start with the "why". Why are we building this? What do we hope to achieve? How do we know this is actually worthwhile? These are not always part of the technical spec, but they are an important precursor. And yes, I know that "validate your assumptions with quantitative data" is the sort of Boy Scout answer that sounds great on paper and is much harder to do in practice. Your justification does not have to be an iron clad assertion that you can prove in court, and realistically it probably cannot be. But you need something anchoring the why. You can't (shouldn't?), insist on requirements based purely on vibes.

Once you cover the why, it is time for the "how". So how (heh) do you do that? Like most things in life, the answer is in the details.

Try walking through the customer flow you are trying to implement for a specific class of users. Look at similar flows that already exist and try to understand the systems and status quos supporting them. Walk through the implementation flow with engineers and see what questions they ask. In our example, walking through the customer perspective might reveal that you want sign in links embedded in the email. Talking with engineers might reveal that existing subscription change emails are sent through an event pipeline that you should probably reuse. Talking with data engineering might reveal that subscription data for products A and B lives in completely separate namespaces and will require integration work to connect. Talking with legal or finance might surface audit logging or regulatory communication requirements.

Writing a strong "how" requirement means understanding the landscape of your company. You need to understand which teams will be involved, talk to them about what you are trying to accomplish, and include in your requirement how those pieces are expected to fit together.

The inconvienet truth is: how those pieces fit together will have to be figured out eventually during implementation. If it is not done during requirements, then you are implicitly punting the hardest parts of the problem further down the timeline. They will not be reflected in estimates, staffing, or launch planning. You may not like that this is happening, but that is what is happening. You are deferring risk and then acting surprised when timelines slip.

Doing this diligence early saves time later. It also makes your estimates more realistic and makes your project more likely to be staffed and prioritized correctly. If you are negotiating for engineering capacity among competing priorities, a well thought out requirement is a pretty convincing argument.

Once you have the "what", "why", and "how", you still need the "who" and the "when".

The "who" is usually straightforward. It is the team(s) that own the parts of the solution you identified during requirement gathering. The "when" is also relatively straightforward. It is the estimate those teams provide once they understand the scope and constraints of the requirement.

At this point, you have covered the five Ws plus the how. And you might be thinking, "Damn, this sounds like a lot of work. I do not know how I am supposed to answer all these questions, surely this can't be right?" There is a name for this phase. It is called "discovery". And lack of discovery is one of the most common reasons projects fail.

Conclusion

Writing good requirements is not about creating an iron clad contract that can never change or spoon feeding engineers instructions. It is about analyzing problems within the domain of your company and thinking through implementation and practical implications so your requirement has a fighting chance of surviving contact with reality.

Good requirements will not eliminate complexity or challenges during implementation, but they will reduce late project churn, make estimates more honest, avoid weird tech debt caused by 11th hour hackery, and help prevent projects from living in a perpetual state of chaos.