Writing Specs Like Pro – Part 2

In the last post (here) I described the outline of what I consider a good product specification (spec). Over the years I’ve found this template to be very helpful in putting my thoughts on paper and it also forced me to focus on the stuff which is often overlooked, such as the feature’s KPIs, analytics and more. I found that this format also works well in aligning all the stakeholders and serves as a decent working document for the R&D.

But providing a template is only the first step. You can find dozens of product specifications templates on the web, with various levels of qualities.

What usually is hard to come by is an actual spec for a concrete feature. I guess it’s because you can’t show off with specs you’ve written for your company as part of your ongoing work (since this is confidential). 

Well, I have good news for you – today I’ll provide you with an actual spec, for a real feature. I decided to ‘ride’ on a recently released feature, by a famous app, and write the spec for it as if I was the product manager in charge.

The app I’ve chosen is Whatsapp, and the feature I’ve chosen is the ability to join group calls after the call was initiated. Here, I think this blog post summarizes it all very nicely.

I’ve chosen this app & feature because the app is well known, and the feature is simple enough to make a compact spec.

Here is the spec I’ve written for it:

Whatsapp Join Video Calls Spec

Now for the disclaimer part: 🙂

1. I wrote it in a bit more than 1 hour. It’s probably missing some requirements here and there. I don’t think it matters. What matters is that you’ll get the drift and see the level of granularity I’m aiming for.
2. All the specs I write go through a ‘spec review’ where all the internal stakeholders share their thoughts. There are always comments and feedback, and following those the resulting spec never looks like the original one. This one hasn’t gone through any review so it’s surely missing stuff and other stuff needs to be corrected. Help me make it better by providing comments on this post.

So, with the above in mind – feel free to go over the spec. I think it’s quite straightforward.

I do want to provide some notes and draw your attention to questions that often come up by product managers I mentor:

• The first remark is regarding the KPI section. As you can see in the spec, I provided concrete goals in terms of KPI lifts that I expect following the release of the feature. I am often being asked ‘how do you know what lifts you should expect?’.

I understand where this question is coming from, but I think it’s wrong. It’s not about what we should expect but rather what would make this feature worth doing. Meaning – if I don’t see minimum uplift in the KPI – then sadly I won’t be able to view this feature as a success and it was probably wrong to work on it in the first place. It goes back to the ‘why’ and the value behind it. If the expected value is not bigger than X (and you should know X before you started working on the feature) – then don’t work on the feature…

And if you did and eventually the delivered value is below X then either you can iterate and fix easily, or the whole bet was a mistake. Now, sometimes it’s ok – we make bets and they fail. It’s part of the experimentation process. Just don’t make failure part of your constant experience. Let’s learn from it for the future as for how to improve our bets.

• My second note is about the level of granularity. I am positive that some of you can’t help wondering whether I shouldn’t have gone into a deeper detail with the functional requirements for each of the user stories. For example – some of you may feel that the first user story (about the ‘join’ functionality) is oversimplified. I don’t think so. How can I tell? Well, my personal test is asking myself if I can add any additional information without delving into the ‘how’ (the implementation details). If I can’t find a way to add new details without starting to dictate some sort of implementation – then I should probably stop at this point.
  Yes, indeed it means that sometimes, from the product standpoint you will write a single sentence, but from the R&D this single line means a couple of sprints worth of work. As long as the developers know what they need to do, how it’s gonna be measured and what’s the success criteria – we are good!

• The opposite danger of the previous bullet is to write the spec in a way which is too high level. For instance, on the third user story (the ‘call screen’) I went ahead and described several edge cases and how they should be treated. I might have ignored them and focused only on the ‘happy flow’ but this may result in the developer and the QA missing those out and it may find its way to production. When I consider adding edge cases to the spec I ask myself – Is this really an edge case or somewhat a normal flow which is simply not the ‘happy flow’? And what will happen if it’s untreated and finds itself in production?

If the answer to the first is that this flow may be experienced quite often or the answer to the second ‘disaster’ – then you should include this flow in your spec.

I’d like to keep this post short and to the point. Therefore I’ll stop here. If you have more questions/remarks about this spec – feel free to comment on this post.

As for the example spec – feel free to share it with whomever you want. Will appreciate an attribution though it’s not a must.

Thank you, and until next time 🙂