Most people groan when they hear “product spec”. They think of weeks spent writing docs that no one reads. How can one be agile, and pumping out code like a ninja-rockstar, if one is encumbered with documentation? After having spent over a decade building software products used by millions of people, I think this view is misguided. In my experience:

Effective product specs are a critical part of building great software. They force critical thinking up front, scale communication, and raise accountability — all leading to higher quality, lower schedule risk, and less wasted time.

In this post I’ll walk through an example, and share some general advice. This will be most useful for product managers in mid-to-large companies (200+ people).

First, an Example

Suppose you work at:

A company that runs a vacation booking site (like Hotels.com or AirBnb.com but smaller). Your checkout conversion is low, and one idea the team wants to try this quarter is live chat during checkout.

Your ticket/story/roadmap says:

Try adding live chat to checkout to increase conversion.

Checkout conversion is only 18%, whereas the industry standard is 30%. Let’s test showing customers live chat during checkout to see if we can improve it. Customer ops has agreed to lend us 1 head for a month.

And you execute without a spec:

Let’s say you decide that action is paramount, and jump right into it:

You chat about this with your team in the sprint planning meeting. Then you simply pick a reasonable chat vendor (like SnapEngage). Update the ticket to ask a developer to slap in some Javascript. And have a meeting with Support to make sure they’re all set.

Bam! Why do we need all that spec fuss anyways? Well if you’re a small startup, you don’t — because there are fewer moving parts, and fewer people involved. But if you’re in a larger org, or have a more mature/complex product, the details will appear at some point, and they’ll cost more to address later. For instance:

A dev marks the ticket as done, but on giving it a spin, you realize it doesn’t work on mobile. → Doh! You forgot to mention that mobile is key.

The customer ops manager wants to have a lengthy vendor review to pick the right chat tool. → Ugh. Schedule a meeting to explain this is only a test.

An hour after launch, support says they are getting live chat requests in Spanish. → Yikes! Do an emergency release to limit to English only.

A designer spends days crafting the perfect slide-in animation to display live chat. → UX gold-plating. Did you set expectations that this is a test?

After a week of testing, BI realizes they can’t build the report you need because the right metrics weren’t logged. → Epic fail. Restart the test.

Without a spec, you might not have a disaster on your hands (this is a relatively simple project), but you will likely waste time and opportunity.

Now suppose that you wrote a spec:

To illustrate, I’ve written up what early notes might look like, as well as a completed example spec — so you can see what the evolution might look like. Take a few minutes to go and read these before coming back.

Read example notes. (2 min read)

This is a bulleted brain dump of what you know, and questions you want to answer. Write this up front by yourself. It should take about an hour. This is your straw-man to vet with your team and stakeholders.

Example of notes you might take to get the process started.

Read the example spec. (6 mins)

You’ll only feel confident writing this after vetting your assumptions and ideas by your team (in small focused meetings, over coffee, or on a foosball break). Once that’s done, this spec should take 1–3 hours.

Example of a completed spec.

Aaah, doesn’t that feel more solid? Writing a spec may seem like extra work, but it’s not. Effective specs will help you and your team save time, and deliver with confidence.