How to write product specifications

My golden rules to make sure your product is shipped right.

The Product Manager is often described as the “bridge between business, design and tech”. The bridge “between design and tech” part is especially critical when it comes to shipping a quality product: bug-free, pixel-perfect and that takes into account all possible scenarii and edge cases. To make sure that bridge is functioning well, here’s several ways it’s handled by the design team:

• The designer ships a comprehensive prototype, that shows all the flows of the product. Unfortunately, this will often times take a lot of time and will still miss a few edge cases.
• The designer will only ship a prototype that shows the main flows of the feature, and remains available for questions from the development team. Unfortunately, these back and forth are highly inefficient (especially in a remote setup) and waste a lot of time from both design and development team.
• The designer, in addition to the comprehensive prototype, writes a proper specifications document that lists all the possible scenarii and edge cases. The problem is that it’s often a waste of time, because (1) designers’ precious time will be better spent by actually designing other features, not write a spec doc, and (2) they don’t always have the same 360° view of the product as product managers do, which will cause them to overlook some scenarii and edge cases.

That’s why mature product teams usually entrust the writing of their product specs to product managers.

But how should you write product specifications? I’ve written product specifications for the past 5 years and I found a format that is well appreciated by the software teams I work with. In this post, I’m sharing more about my methodology and the tools I’m using to write product specs. I’m also describing some limitations that I’m facing with the tools I’m using and some ideas of improvement I have in mind.

5 pillars to a solid product spec

Here are the 5 main topics that I address in a product spec:

1. Context and objectives
2. Architecture map
3. Epics and User stories