In the realm of product management - when you want to build something great you’ll probably write a product specification (may be referred to as a PRD in your workplace). If your product specification is badly written, then the end result may be totally off from what you originally planned, or even worse - there won’t be an end result at all.

On the positive side - if you do get it right and clear - then you significantly increase the chances of having your feature released fast and as you envisioned it.

So, yes – today we are going to cover how to write the perfect product specification (well… this is a bit ambitious… So let’s say – a ‘very good’ one). Such a specification will create an alignment between all internal stakeholders and get things built properly.

Here is the agenda:

I’m going to divide this into two posts. Today I’m gonna cover the ‘theory’ by going over what a product specification must contain and where the pitfalls are. I’m going to provide a template you can use yourself if you wish. 

In the second post I’m gonna show you a spec I’ve written specifically for this series which demonstrates an actual implementation of what I was talking about. For that I took a recently released feature from a famous product, and wrote the spec for this feature as if I was the product manager in charge (which feature and product? Well… read the next post to find out).

 

Ready? Let’s go!

 

The Rationale Behind a Product Specification

First, I’m gonna use the term ‘spec’ from now on, as it’s quite annoying to write ‘product specification’ each and every time. Some also refer to it as a PRD, but for some reason (which I honestly can’t explain) I don’t like this term.

 

Now, what is a spec and why do we need one?

Well… the answer is quite obvious I guess – we need a working document that will create an alignment across all internal stakeholders regarding what needs to be built.

If you adopt my principle of having a ‘single source of truth’ for every step of the delivery process (see here) then you can say that a spec is the single source of truth for the ‘why’ and the ‘what’. Meaning – this document explains exactly what needs to be built and why we are building it.

Any communication about the feature that goes through Slack channels, emails, verbal communication or whatever – needs to be cascaded back into the spec. Hence – if it’s not on the spec – it doesn’t exist and was never agreed on.

 

Do I need to write a spec for each and every feature?

No. Some features are quite small so you can skip the overhead involved with a spec and a spec review and simply write a Jira ticket (or whatever system you use).

However, even in the simplest Jira ticket, when writing the feature request it should encompass the why and the what (even if you do it all in a single paragraph). Otherwise, it may raise questions and you’ll need to provide repetitive explanations as for why this ticket is being prioritized.

Your take away here is that the size of the feature determines whether a full spec is needed or not. If you are in doubt – go for a spec. It’s more work, I get it, but if you are in doubt – most chances are that things are only going to get more complex and not the other way around…

 

How a ‘very good’ spec needs to be structured and what should it contain?

Great question! This is why we are here after all.

Below you’ll find a list of the sections I recommend, and at the end of the post I’ll provide a link to an empty template you can use. Let’s go:

 

Overview

The overview section is all about the ‘why’. Yes, you should provide some background about the feature for those who are not familiar with it, but the main essence of the section is about why we decided to go for this feature. Specifically it should include:

1. Short background (1-3 sentences)
2. Why we want to work on it
3. What data points support this decision (customer requests, usage stats, etc..)

 

Goals

This section is about the actual new capabilities that need to be delivered when the work is done. For example: “It should be possible to export the users list to a CSV file with one click of a button”.

You can also describe a business goal if there is a clear one. For example – “Reducing the complexity of the system, by reducing the number of actions the users need to do in order to accomplish [whatever]”.

If the feature is complex it’s possible that we’ll have around 1-3 goals that need to be accomplished.

 

KPIs/Success criteria

This section is very important and very often overlooked by product managers, or not properly written.

Ideally, this section will define how you measure whether the feature delivered all of its theoretical value (delivered value to the user and captured value to your company) and whether you can consider it a success. This can be achieved by defining the KPIs for the feature.

The main pitfall I see here for product managers is to define something too vague or that cannot be measured. For instance – ‘reduce users’ churn’. 

Not very useful, right?

When you define a KPI that will measure the success or failure of your feature make sure that:

1. You use a well defined metric which is easy to measure
2. Set the minimum goal for it to be a success (for example – ‘at least 20% increase’ in [whatever metric you chose])
3. Tell when you’d expect to see the uplift or the drop (two weeks after release, immediately, etc..)

 

Here is a concrete example:

KPI1 – 1 month following the release we expect to see at least 15% uplift in the CTR of the ads shown.

 

Now, sometimes – we can’t define a KPI for a feature. I know some of you will argue that I’m wrong and it’s always possible, but I will insist and say that in the scenarios I’m talking about – if you are determined to put a KPI on the feature – it will probably be an artificial KPI which tells nothing and proves nothing.

What scenarios am I talking about?

I am talking scenarios where either:

1. The users won’t feel any change, and yet you must do it (for example – fixing a security breach)
2. The users will see the change, but it’d be impossible to correlate the change with any business metric changes. For example – adding a new file format you support when downloading some data files. Yes, it has been requested by some users – but by itself – it’s very unlikely to have a major effect on whether they will keep using your product or not. Still – you must do it, because together with some other small features – the accumulated effect will be in your favor.

 

So if you are convinced by my arguments – then in such cases – instead of defining a KPI, I’d define a success criteria which can be easily measured or verified (‘the file in the new format was created and downloaded within 5 seconds’).

 

User stories

This is where you define all the user stories that make the feature. I assume I don’t need to explain what a user story is. You can Google and read about it if you are not familiar with it, but the gist of it is that it encompasses a short description of a needed functionality from the point of view of the major stakeholder who could benefit from it. The user stories by themselves represent only one part of the feature, but this part does provide an incremental value, even if it’s not the full feature.

Hence, any user story you add must:

1. Provide value on its own
2. Be a crucial part of the whole feature

 

When all the user stories are implemented – the feature is ready.

For example – if you are working on a feature that schedule reports to be automatically created and sent to the users then users stories that may make sense are:

1. Exporting the data to the desired format
2. Support sending the file via email
3. A scheduling mechanism (backend)
4. A scheduling mechanism (frontend – UX/UI)

 

Personally in this section I usually use a table where each row describes the user story, where the first row is the EPIC. Meaning – the first row describes the whole feature in a language which is similar to how user stories are written.

I don’t provide the detailed requirements in this section at all.

What’s the value of writing it this way?

It allows the reader to quickly understand what building blocks will be required to make the feature. I’ve personally experienced countless times how this high level view enables readers to quickly digest the essence of the feature and what it will take to build.

 

Detailed Requirements

In this section you take each of the user stories and break it to functional requirements.

It sounds simple, and indeed it is. However, for some reason, this is where the great majority of product managers fail big time from what I’ve observed. They either compose the requirements from ‘a 50K feet altitude’ or do the exact opposite – write it in too much detail.

The problem with the first is that the engineering team doesn’t have enough ‘meat’ for understanding what exactly they need to do – and you may get an end result which is far from what you wanted.

The problem with the second is that you are drifting into the ‘how’ and out of your realm. How to implement a feature is the decision of the R&D. Not yours. By insisting to dictate parts of the ‘how’ you may run into unnecessary conflicts with the R&D or simply dictate something that can be implemented in a much simpler way. This is true even if you have an engineering background (trust me, I’m an engineer :-)).

Anyway – in terms of format – just make sure it’s easy to correlate between detailed requirements to the matching user story.

 

UX/UI Design

This is where I’d link to the UX/UI specifications for this feature. The reason that I’m linking and not embedding is because the designers are hosting their designs on other platforms such as Figma, Zeplin or whatever. If you want it to exist within the document then they’ll need to copy & paste it, and it becomes static. Meaning – each time they make a change they’ll need to copy & paste it again into your spec.

By linking you provide direct access to something which can be dynamically changed given comments or reviews.

 

Another approach would be to include the UX and UI within the functional requirements, but from my experience it just clutters things without adding too much value.

 

Analytics

In this section you define all the analytical questions you may be interested in querying, once the feature is out there, for understanding how this feature performs in the real world or how it affects the overall picture. For example – ‘how do the users who use this feature breakdown by geo?’, ‘what is the activation rate of this feature’ and so forth.

The R&D needs to treat this as additional requirements and make sure they embed the proper logging and analytics events in their code, or otherwise this data won’t be available for you and you won’t be able to make data driven decisions.

For some mysterious reason, I never saw a product manager who adds this section (or something in this spirit), and I’m always wondering why. How many times has it happened to you when you released a feature and when you asked your data analyst (or the engineering team with a lack of one) one of these questions and they replied “mmm… oops… we didn’t log this information”.

 

The second benefit of this section is mainly to you. It forces you to sit down for a second and decide how you are going to analyze the feature’s performance. Doing it in advance will save you a lot of time. Believe me.

 

Other sections

Usually, with the analytics section written – I’m done. Sometimes, though, it makes sense to add another section or two. For example – when the feature has some potential security vulnerabilities – you may want to devote a section for security. This is up to you.

Just make sure you don’t add too much stuff or no one will actually read it. No one has the patience for endless scrolls.

 

Great! What should I do after I have the spec ready?

That’s a very good question but a bit out of scope. In short – you should proceed to a spec review with all the internal stakeholders (see the link I provided above to the post about the delivery process). Apply the comments and hand it over to the R&D.

 

Before we depart and with the above information in mind – I’d like to provide a link to an empty template, which is based on the above. Feel free to use it as you see fit. Here it is:

A product specification template

 

Next post, as I’ve promised above – I’m gonna take an actual feature and write a full product specification which is based on this template. 

 

And that’s it for today!

If you found this post/series useful – feel free to ‘like’ it. If you think others can benefit from it – feel free to share it with them.

 

Thank you, and until next time 🙂