On Writing Product Specs

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:

1. You chat about this with your team in the sprint planning meeting.
2. Then you simply pick a reasonable chat vendor (like SnapEngage).
3. Update the ticket to ask a developer to slap in some Javascript.
4. 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.

STOP! —Have you read the example spec yet? Read it now, please.

A Guide to Writing Specs

I started with an example to anchor the ideas presented in the rest of this post. Do make sure you read the example spec before continuing.

Why write a spec?

To ship the right product with higher quality, speed, and predictability.

Yeah, that’s it. Now, how does a spec help you do that? Horowitz says it well above, and my example illustrates why, but here it is for clarity:

1. Do critical thinking up front
   Writing forces you to think through specifics, in prose, before the expensive work of architecture, coding, design, qa, etc. takes place. It raises the quality of your decisions, and reduces the chance of surprises.
2. Communicate efficiently
   One way or another, you will communicate your proposal to various stakeholders (support, engineering, design, finance, management, etc.). A spec allows you to batch this communication, and to do it without ambiguity so your team can grok and respond intelligently.
3. Raise accountability
   By publicly committing to measurable goals you align the incentives of the team: stakeholders will realize how unreasonable last minute requests are, and engineers will think twice when making estimates.

What should a spec contain?

Your spec is a clearly communicated decision on what to build, and why. There are many ways to express your ideas in a structured manner, but at the heart of it, you must address these five things:

1. The Problem
   Frame the problem that you trying to solve. More importantly, explain why it is worth addressing. Be specific, and provide metrics.
2. Measurable Goals
   Promise clear deliverables and outcomes. Identify what’s out of scope. Make sure it’s easy to look at each goal and answer: did we hit it?
3. Context
   Provide evidence that your audience needs to understand the problem and believe in your proposal. Assumptions, use-cases, metrics, etc.
4. Detailed Solution
   Your proposal should be detailed enough for your team to consume and execute — think of it like code for human brains to run[1].
5. Timeline
   List dates and milestones that your team believes in. This section may start off vague, but should be finalized in your last spec review.

Use the example spec above as a template for writing your own. Add/remove/move sections as you see fit, the narrative structure doesn’t matter as long as you address the above points in a clear and specific manner.

How to write a spec?

Here’s the general process that I follow to write and review specs. It can vary by project size, number of stakeholders, etc. but this is the general flow:

1. Write a quick draft (1–2 hours)
   Close Slack and your email. Brew some tea. Sit back and think. Then jot down what you know in bullet form (see example draft from above).
2. Setup a couple of 30 minute 1–1 meetings (1–4 hours)
   The aim is to work through assumptions, improve your proposal, and get buy in. Keep these meetings tiny and focused with as few people in the room as possible (ideally 1–1s). For the example, I would setup 3 meetings with the support manager, a finance person, and an engineer.
3. Write and edit the spec(0.5–3 days)
   At this point you have a pretty solid idea of what can, and needs to be done, but a lot of details will be swirling in your head. Put it all together with some critical thinking and writing. And when you have a draft: do a lot of editing. You can usually make your first draft 30–50% shorter, and it’s worth it: brevity and clarity will result in it being read. Most specs can be written in 0.5–1 day, but substantial projects may take 2–3.
4. Publish and setup a 1 hour review (15 minutes)
   Send a wide email with your stakeholders on the “to” line, and other interested parties on the “cc” line (e.g. your product team, the broader support org). Follow up with a meeting invite for key people: those who will do the work, and those who have veto/approval authority.
5. Review the spec (1 hour)
   Start your spec review meeting by asking who has not read the spec in detail. There will usually be 1 or 2, in which case, say “no worries, let’s take 10 minutes to read the spec, if you have read it already, feel free to take a break”. Use this meeting to get sign off from stakeholders and get understanding and commitments from the doers (Dev, Support). You may need to revise and repeat this step based on what you learn.
6. After the review, send an update and file tickets (1–2 hours)
   Your email should point to an updated spec, the tickets related to the project (e.g., add Javascript code, write BI reports, QA in our staging env, do a dry-run with Support team, etc.), and a rough date on when you’ll update the group next. Often, the next major step will be for an engineer to write a tech spec, but not always (my example doesn’t need it).

What are some pro-tips for writing an effective product spec?

1. Keep it short
   No spec writing advice is more important. Brevity forces clarity of thought and communication. It also means that your doc is more likely to be read and understood — because that’s all that counts.
2. Use plain English and simple formatting
   Use shorter and simpler words over fancy ones. Use bullets and bold styling to make it easy to scan your doc. Write in a casual style, and make it interesting. Use humor if you can.
3. Stay ahead of your dev team
   A completed spec is one that has been reviewed and generally agreed upon. If you’re hoping to slot in work into a future sprint, make sure you start this process 2–3 weeks before.
4. Think like an engineer
   A lot of edge cases appear when one finally sits down to write code — but that doesn’t have to be the case. If you think through what it will take to build it, you’ll address them early (e.g., does live chat work on mobile?).
5. Bring everyone on the journey
   By the time I do a spec review, most people in the room have a general idea of what’s coming — because I’ve vetted it in small focused meetings and informal chats. This means I’ve done my job in communicating the what and the why, and now we’re just focused on the details.
6. Work hard on images
   Like flow diagrams, or wireframes. They can convey huge amounts of info in an easily digestible manner, but can also take lots of time to make.
7. Spend 0.5 to 3 days thinking and writing
   Depending on how large the project is. More time than that usually results in diminishing returns, especially because nobody will read a doc that is longer than 5–6 pages.
8. Set direction and point at the vision
   You’re not just defining this one feature, but you’re also providing context on why we’re doing this and where we’re going. Point out how this project affects the grand plan, and what things may come next.
9. Make sure your Audience reads it
   If your spec is too long, confusing, or just not shared with the right people, you might as well not write it. Make sure it is read. See my tip on reading it at the start of reviews.
10. Get honest feedback
    Are your specs specifying the obvious? Or don’t have enough detail? Are we finding too many edge cases later on? Or are we spending too much time in planning/review? Ask your team.

But what about Agile and Scrum?

I know I will raise eyebrows, but specs are fully compatible with the principles of the Agile Manifesto, and are essentially represented in methodologies like Scrum — after all, don’t stories need more meat put on them at some point? Why have verbal and whiteboard sessions, only to then lose the clarity and communication value that comes from writing it down?

The view that specs result in slower releases, over-planning, and generally wasted time is unfounded. Multiple world-class teams I have worked on followed several agile principles (like 2-week sprints), shipped code daily (or more), and measured their success on product shipped (not documentation or meetings) — yet still prized specs as a key part of their process.

And what about tech specs?

I’m a huge fan. While product specs focus on the what, tech specs focus on the how. They bring the same clarity to a different part of the building process, and ultimately make engineers (and their customers) happier. I may write about tech specs in a future post if there is interest.

In Conclusion

Thanks for reading this far. If you’ve found this post useful, please do share with your product and engineering teams. Happy speccing!

Read the next post in the series: On Product Roadmaps >>

Footnotes:

1. Joel Spolsky (early PM at Microsoft, and co-founder of Stack Exchange, Trello, FogBugz, and more) is to thank for the spec-as-code-for-brains analogy. Back in the year 2000 he wrote a 4 article series on specs, that has been a huge influence on my PMing approach. Great reading.
2. In the quote at the top, Bezos is talking about memos prepared for, and read in his senior executive meetings, typically for new business/product ideas. They aren’t exactly product specs, but two aren’t that far apart. Bezos requires silent reading time at the start of the meetings — which is what inspired me to encourage the same in my spec reviews. Source.
3. Thanks to the iDoneThis blog for their nice post on the value of writing. It is the source for the Bezos and Horowitz quotes above.