How to write clear product specs

There is no use delaying the disappointment: telling you how to write clear product specifications will keep you busy for a while, but it will not save your project.

Why?

Because everybody knows you should plan your work and work your plan: that knowledge alone is not sufficient. Only an idiot’s jaw drops upon learning that they can lose weight through… wait for it… exercise and dieting. Everybody knows that, and yet we hurl billions of dollars at the weight loss industry hoping for some magical workaround to spare us the pain of hard work.

So don’t bother reading any further if you are expecting some corner-cutting cheat code that will let you jump your place in line — if that’s your game, then I got a diet pill to sell you (hell, you might have one to sell me).

Instead, this article will take a tour of the unglamorous and inconvenient truths about how we relate to our commitments, and that (more than any superficial goop), will challenge how you approach your communication within your team and its projects.

Big little delusions

Consider for a moment the last work meeting you attended. Did it start exactly on time? Did you arrive early? Or did you wander in with a cadre of coworkers a wee bit after the hour? And more importantly, did you even notice? Or was this behavior so commonplace that it was overlooked in its insignificance as a non-event?

The purpose of this questioning isn’t to recruit time-Nazis, it is to point out how utterly out of touch we are with the most basic tenets of integrity. It may not be as racy as cheating on our spouses, but we are not keeping our word. We say one thing, yet do something else entirely. The principles of scheduling are fantastically simple: you commit to being at the agreed on location at the agreed on time. Period. And yet, holding people accountable to that simple commitment proves somehow enormously difficult.

Why?

Perhaps we justify our tardiness by telling ourselves that there were no serious consequences. In that sense, we aren’t fulfilling commitments so much as avoiding punishments. “I’m late because I just got off the phone, because I’m having one of those days, because I thought it was more like a soft 10, because I was getting my coffee, because blah blah blah me me me I am exceptional and I am not beholden to your rules and this defiance is a testament to the survival of my Freudian self!”

The excuses are endless, but the results are the same. Whether deliberately or not, your calendar has become a ledger full of lies because you and your merry mutineers simply do not do what you said you would do.

Admittedly, this forensic analysis of our latest office meeting is overly draconian. However, as a spec, a calendar invite is as simple as it gets, and yet we still fail to fulfill it. By comparison, our products have conditions of satisfaction far more complex. So why do we expect punctuality and thoroughness to emerge in one instance when in all others we have conditioned ourselves to never rise to that occasion? It is downright delusional.

Discussing product specs without addressing the flaws inherent in our communication brings to mind Shel Silverstein’s poem about a homemade boat: “The sides and the back are divine — it’s the bottom I guess we forgot.” We must look beyond merely documenting requirements and towards ways of holding ourselves accountable if we want our project to float.

What is a product spec?

For the sake of clarity, let’s define our subject thoroughly before we continue. Exactly what is a product specification (spec)?

A product spec is a planning document that provides the thorough context of a product by enumerating its goals and the detailed conditions that a solution must satisfy.

As its name demands, a specification must be specific, its details measurable. The spec should specify what is needed. As much as possible, a spec should not concern itself with how these requirements are met, because there may be multiple viable options that fulfill the needs.

For example, the requirements for an automotive braking system may define the maximum allowable stopping distance for a vehicle traveling at different speeds, but it does not stipulate whether the system relies on disc, drum, or anti-lock brakes. Requirements such as cost or performance, however, may eliminate certain options.

Measuring success

Now that we defined what a product spec is and we have made mention of the human tendency to fudge commitments, we can begin to address the single most important thing that our product specs must include: measurable deliverables.

To borrow from the Objectives and Key Results (OKR) framework, results must always have a measurable number, stripped of any flaccid descriptors like “faster” or “better”. How much faster? What do you mean “better”?

If our team desires success, our team must agree on how to measure it. How else will we know whether we have failed?

To discuss this critical aspect, all stakeholders must agree to live in the same universe. The terms for success must be so clearly defined that a neutral third party would have no trouble evaluating them. If the various factions cannot find common ground in the definition of the project’s success, then the project is doomed from the start. Remember that it is always better to fall apart in the planning phase than it is to blow-up in midair with the blood, sweat, and tears of multiple collaborators onboard.

When you start thinking in terms of measurable accountability, you may notice yourself sounding like a contractor, because any good contractor will clearly identify deliverables and timelines so that it absolutely clear what work is to be done and what the client expectations are. Likewise, a good contractor will avoid projects lacking a clearly defined scope (or perhaps they will merely increase their rates and insist on hourly billing).

The importance of agreeing on valid measurements cannot be overstated: most failed endeavors can trace their collapse back to incomplete or poorly chosen measurements.

Politics

Like it or not, measurements and specs are inherently political, and fighting for clear and accepted measurements in your specs democratizes your work and provides a safety net for all those working under them.

Who benefits when a product’s stated measurements are imprecise? In most cases, it’s the management who comes out ahead because they are the ones who can declare a project a success or failure. Without the protection of transparent measurements, stakeholders can incriminate or glorify whomever or whatever they wish. The assessment of success can quickly devolve into your word against theirs, and the pecking order usually predetermines the winner.

Beware for whom lack of accountability is a feature, not a bug, for theirs is a Machiavellian power struggle from which no undertaking can escape unscathed. In the proximity of such doublespeak, success takes on a cult-like quality. Instead of projects surviving through multiple iterations and personnel changes because they are nurtured by a transparent system of standards, they live and die with their authors. The team plods ahead in an unspoken oath of fealty carried out with bureaucratic insipidity, more or less resigned to “agree to agree” with whatever vision the leader has imagined for that moment. RIP accountability and any chances of lasting success.

Dialogue and feedback

Now that we have discussed the risks of improper product specs in a somewhat dramatized fashion, you may keep a sharper eye on their quality. How can you tell if a product spec is properly written? Keep open an unflinching eye for any vagueness or anything that could be misinterpreted.

Experience will help you preempt problems, but sometimes shortcomings in the spec only reveal themselves after you have dug in and are trying to implement a solution. In other words, the proof is in the pudding.

The product spec symbolizes the ongoing dialogue that takes place between the product and engineering teams. As your team gains experience, the communication will improve and questions will be preemptively answered in the spec. Specs will always require clarifications, so your team must provide a viable feedback mechanism. It is rare that the spec emerges unchanged after development has concluded.

The jungle

Some of the trickiest problems involving specs are the ones that are not immediately obvious. To illustrate this, we can take an uncomfortable look at the food industry. When you go to a restaurant, the description of a dish on the menu represents a spec; the food the waiter brings you represents its fulfillment. You make a lot of assumptions when your spec is as short as an item in a restaurant menu. Your meal may nourish you, but what must you assume about the quality of the food or the level of contaminants, to say nothing about the temperature of the grill, the conditions in the production facility, or the wages of the workers?

Whereas food concerns itself with health standards, software concerns itself with development standards. If your organization and its product specs make no mention of coding standards, then product implementation faces risks akin to eating contaminated or undercooked food. There must be a safety net of standards to protect the projects, otherwise, developers will be pressured into taking endless shortcuts, tech debt will accumulate, and the code bases will eventually perish from binary botulism.

To inoculate against this, make sure your organization has well-defined coding standards, thorough tests, and meaningful code reviews. Many organizations skimp on this level of detail, claiming that there simply isn’t enough time: the product must ship! However, if proper accounting were in place, the true cost of improper or incomplete solutions would become apparent. Many organizations claim they don’t have time to define and enforce standards, yet they hurl endless hours at patching up problems and writing ugly hacks to keep their shoddy solutions afloat. Only an organization that spurned accurate measurements could possibly make the claim that taking shortcuts saves time in the long term.

Conclusion

At the end of the day, writing good product specs is all about having integrity in communication and action. Through practice and repetition, your organization will create a culture of accountability and your projects and skills will improve. Keep an eye out for any indication that the product and engineering teams may not be on the same page. If the engineering leadership thinks it knows better than the product people as to what needs to be built, or if the product leadership cannot be bothered with the technical details, those are warning signs that signal poor or incomplete communication and all projects are at risk.

If anyone is unclear as to what the priorities of the business are, that too portends dysfunction. Communication is the remedy to this problem, you just need to initiate it.

By walking through the subtleties of communication and the political pitfalls that can accompany missteps, you become more aware of the form that good solutions must take. A culture of integrity and transparency is ultimately the most important thing for any product and its specs: great products do not emerge from a vacuum, they germinate in an atmosphere of impeccable communication and transparent measurements. To paraphrase Mahatma Gandhi, it’s up to you and your team to be the change that you wish to see.

Plug: LogRocket, a DVR for web apps

LogRocket is a frontend logging tool that lets you replay problems as if they happened in your own browser. Instead of guessing why errors happen, or asking users for screenshots and log dumps, LogRocket lets you replay the session to quickly understand what went wrong. It works perfectly with any app, regardless of framework, and has plugins to log additional context from Redux, Vuex, and @ngrx/store.

In addition to logging Redux actions and state, LogRocket records console logs, JavaScript errors, stacktraces, network requests/responses with headers + bodies, browser metadata, and custom logs. It also instruments the DOM to record the HTML and CSS on the page, recreating pixel-perfect videos of even the most complex single page apps.

Try it for free.