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.
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:
- 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. - 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. - 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.
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:
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.
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:
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.
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.
Thanks for reading this far. If you’ve found this post useful, please share it with others — especially your product/engineering org. If you’d like to see more product management content (e.g., roadmap planning), or want to learn how others are using specs, please take this 2 minute survey. I’ll share any interesting results in a future post. Till then, happy speccing!
