📝 Writing specs

How to write a great product specification

TLDR

Good product specifications bring clarity and focus and help your team hit a high cadence. The spec is a clearly communicated decision on what to build, and why. It should help your team align on three things: 1) the problem, 2) the solution, 3) the execution. 

✍️ Write your way to success

Writing product specifications is one of the most high-leverage activities for a PM. It improves outcomes in four ways:

1. Forces critical thinking upfront
   Writing forces you to think. Often, it exposes how sloppy our initial thinking was 😅. Clarifying your thoughts upfront reduces gotchas. Fewer gotchas mean less waste of your team’s time and respect. 

2. Helps communicate efficiently

   Product specs create a single source of truth. People can discover the truth async, at a moment that suits them. There’s no need to get the team together to explain every single detail.  And when you respond to a question, everyone knows the answer.

3. Raises accountability
   A written document is a strong commitment to your plan and goals. It helps avoid excuses and last-minute scope changes.

4. Builds knowledge base

   Specs can be used for later reference: Why did we do this? And why did we build it this way? Your understanding of process and product will improve with each iteration. This compounding effect (helps your strategy and execution improve over time.

A great spec will improve outcomes for users, and save your team hours of work and discussions. PMs, this is our time to shine!

☑️ The ingredients of a great spec

Your spec is a clearly communicated decision on what to build, and why. There are many ways to do this, but at the core you want to align on three things: 1) the problem, 2) the solution, 3) the execution.

Problem

• Problem definition
  Frame the problem you are trying to solve. The more specific, the better. Quantify the problem by adding key metrics and other data points. When you’re lacking data on certain aspects of the problem, you are making assumptions. Make sure these are made explicit.

• Success criteria

  Describe what success would look like. What metrics are we trying to move, and where do we think we can move them?

• Context
  Add extra context that is required to understand the project. Think about previous work in this area, extra information on users, etc.

Solution

• High-level approach
  Describe how you plan to tackle the problem in a few sentences. This should be enough for the reader to get ideas about solutions (e.g if “the problem” is that users do not finish creating their accounts, “the solution” might be to remove steps from the registration process)

• Key features and flows
  Provide an organized list of features, with priorities and sequence. Link to design files that explain the main user flows in more detail.

• Scope
  Make it explicit what is or isn’t part of the project. Deciding what is out of scope upfront does miracles for your execution.

Execution

• Milestones
  Break the project down into smaller deliverables, reducing complexity (our holy grail😇).

• Timelines

  List due dates for each milestone that your team believes in. Please collaborate with your team on estimating this.

• Roll-out & test plan
  This part doesn’t get the attention it deserves. Knowing how you are planning to launch shapes the project. An example: Do you want to do a phased roll-out to reduce risk? Then you will need feature flags. 

⭐️ Pro tips on writing specs

Put the right process in place

• Start on time
  Spec’ing is an iterative and collaborative process. This takes time! Therefore you should be well ahead of the development work of your team. For me, 4 weeks works best.

• Use a template
  Remember our rituals? We want to do the same things in the same way. Templates help us do that. Following the same format helps ensure your spec is comprehensive (you don’t miss critical points), and easy to digest across your organization.

• Collaborate
  Asking for help is a feature, not a bug. Your team and other experts know much more than you do. Use that knowledge! Propose, get feedback and improve. 

Make your spec easy to read

• Keep it short
  Save your team time and keep things short. The goal is to be more effective as a team.

• Use plain English
  I’d take short and simple over fancy words every day, and so does the rest of the world. Bullets and styling make it easy to scan a document. Try to write like you talk. Bonus points for making it fun!

• Visualize
  Visuals can convey huge amounts of info in an easily digestible manner. Your team will love you for it. One little catch; Creating visuals can take lots of time.

Take responsibility

• Think about edge cases
  Don’t be afraid of doing the hard work. What if this scenario X happens? Putting in a bit of love and tears will reduce constant back and forth and show your team you care.

• Own the process
  Send over your spec and follow up. Set a date to discuss it. Don’t get frustrated if people are ill-prepared, but build a system where they have to prepare. In my experience, a fixed rhythm helps with this. 

✉️ In conclusion

Great specs beget great products. For us Product Managers, writing a product specification is one of the few deep-work, high-leverage activities we can do. It’s important! I hope this post helps you improve your specs and build a great product!

---

🏗 Templates

Here are some great templates to get you started. As you see, they are pretty different. Take this as inspiration, then make it your own.

• Figma
  Including a useful launch checklist
  https://coda.io/@yuhki/figmas-approach-to-product-requirement-docs/prd-name-of-project-1

• Intercomm
  Needs to fit on 1 A4, which is a useful exercise.  https://s3.amazonaws.com/marketing.intercomcdn.com/assets/Intercom-Job-Story-template.pdf

• Picnic

  This format worked well for us at Picnic
  https://docs.google.com/document/d/1xm2zSaYW_-xQvPS7crJutyX3OJgtwPl8bPFgKWyX7A4/edit#