Tips in Writing A Quality Product Spec

Question: When writing specs, how long should they be?

Tldr version: Long enough to get the point across.

The goal of a spec is to recreate the image of the end product that is in your head in the minds of the reader.

If it takes you 1 page to achieve that feat, so be it.

‍

Tips to keep in mind:

1. Make it easy to read, structured with headings and scannable.

2. Contextualize with wireframes.

3. Describing intricate logic? Use a flow chart.

4. Documenting use cases or sharing email copy? Depict in tables.

‍

Organization & ease of consumption matters more than word count.

If you think a point would be better understood with additional concrete examples, don't shy away from writing more.

Just don't ramble. This isn't a teen novel.

How much you might have to write also depends on the caliber of your audience.

For an experienced tech team, you might just have to mention you need an OTP trigger or search facet. A couple of paragraphs will suffice.

However, for a new team, you may have to unpack those patterns in detail with all the edge cases listed out.

So, your measure will vary.

In the end, the quality of a spec is determined by how actionable it is, not by it's volume.