To Spec or not to Spec
26 October 2016 ‧ 6 min read
In the past couple of weeks, I found two diametrically opposed pieces of advice on writing product specs: this podcast with Samuel Clemens, who states that he has a “kill on sight” rule for specs, and this article by Gaurav Oberoi with some great hands-on advice for how to write specs.
This made me wonder – in my own work, do I not question enough that I am writing specs, and how I am writing them? After some deliberation, I still think that writing specs is a good use of time for a product manager, for four reasons:
- A spec clarifies the initial thinking
- A spec helps bring new people on board
- A spec documents decisions along the way
- A spec is a permanent record for the future
I will talk a bit more about each of these points below, but want to make one thing clear from the beginning: in my eyes, a spec can only work as a “living document” that evolves and changes. One of Samuel Clemens biggest complaints was that the spec is outdated by the time you are building the feature – in that case, you are doing specs wrong (or at least not very lean/agile). I have myself been involved in the development of huge, bible-like PRDs that would then be “thrown over the fence” to a software vendor – but that’s not how you should build a tech product in 2016 anymore.
1. Clarifying the initial thinking
In the ideation stage of a product or feature, your brain as a PM can be overflowing with ideas, hypotheses, use cases and so on. Writing them all down in a structured way forces you to make decisions between potentially conflicting ideas and also shows the holes in your thinking that still need to be filled. Of course, you could also just start building and hope that all holes will be discovered and conflicts resolved later, but sitting down for a couple of hours and drafting the initial points of a spec is a very high return on the time invested.
These are the points typically covered in a spec at Yammer that help with this initial clarification:
- Goal: Why are we building this? What is the problem we are trying to solve, the objective we are trying to achieve? How will the lives of our users be better or the success of our product be increased if we build this? An example could be “reducing churn in the sign-up flow”.
- Approach: What is the overall approach we are taking to achieve the goal? We don’t go into detail here, just outline what we are going to build, for example “changing the sign-up flow from 4 to 2 steps”. Hypothesis: How do we believe the user behavior will change due to our planned feature, and how does that help us achieve the goal? In our example, this could be “users will be less frustrated with the amount of fields they have to fill in, so they are less likely to churn.”
- Past research: What have we done in this area in the past, and what did we learn? This is important in order to not run in circles. An example could be: “When we added profile pictures as a fourth step six months ago, sign-up flow churn increased by 5% but new user engagement increased by 15%.”
- Metrics for success: How will we tell whether we reached our goal and/or validated our hypothesis? Will we A/B test this? What metrics do we need to track? What logging do we need to understand how users are using the feature? For our example, this is relatively easy, because the goal is inherently measurable: “A/B test 2-step vs. 4-step sign-up flow. Feature is successful if it reduces sign-up flow churn without negatively impacting other core metrics, especially new user engagement.” In addition, our spec templates have some placeholders that serve not so much as required sections to be completed, but more as reminders to think about these topics, for example security, accessibility, and third party developers.
2. Bringing new people on board
Even if you are working closely with the engineering team when you design the feature, there will be times when you have to bring new people on board with the feature and how it works — for example QA, marketing & sales, or support. For all those times, it helps to have the key points about the feature documented. Of course, you could put these points in an email or a (Yammer) post, in bullet form on a whiteboard, or even on a PowerPoint slide, but guess what: Having them in an updateable document that everyone can refer to as the “single source of the truth” really helps!
This holds especially true if — as outlined above — the spec doesn’t just contain the “what”, but also the “why”. If the rationale for why the feature was built this way is only in the heads of the original PM & design & engineering team, it will be much harder for marketing to describe the benefits, for sales to sell the product, and for support to answer customer inquiries. All of this means that the original team will have to answer to questions from these various other teams again and again. Having this broader context written up helps avoid that, and thereby increases team and overall company effectiveness.
3. Documenting decisions along the way
In the Samuel Clemens podcast, he states that “the spec is the conversation between the product manager and the engineer”. I agree! You can’t foresee all the changes that might happen during the development process, new things you learned, dependencies with other work that’s going on, etc. So you will need to make decisions along the way, and it’s usually better to base those decisions on discussions, and finding the problems that need decisions collectively, than if the PM tries to identify them all up front locked up in a room somewhere.
However, it is also good practice to document decisions. Human perception and memory is very flawed, and we tend to forget things, remember them incorrectly, or even simply interpret the agreement in a discussion differently. Summarizing the outcomes of a discussion and then writing them down for reference during the course of the project is a best practice to avoid having to reopen points again and again. The spec is obviously only one place in which you could document these decisions. Instead, you could write meeting minutes, an email, a (Yammer) post, or keep a running spreadsheet of decisions, etc. Including decisions in the spec has the advantage that it means the spec never goes stale, and the team will have a reason to go back to the spec on an ongoing basis, reminding them of the overall goal and approach as well.
In a quick straw poll among the Yammer PM team, the feedback I got was that about 80% of Yammer PMs use the spec to document decisions, the remaining 20% use some other mechanism. I fall within the first 80% — I don’t always write up the full details in the spec, but I will summarize the outcome, often with a link to a Yammer conversation with more details.
4. Establishing a permanent record
If the spec is kept up to date until the end of the project, it also has an additional benefit: Future projects that work on related areas of the product will be able to benefit from the research, thinking, and learning from this project. A year or two down the line, when some people will have left the company, how do you avoid repeating past mistakes, or not taking into account the lessons learned from similar projects? The best answer to that is: You codify that knowledge.
Again, the spec is only one possible place to do that. It does, however, have the advantage that it already tells the story of what the goal and hypothesis was, as well as the approach that was tried to achieve that goal. Linking the results and lessons learned to that completes the build-measure-learn cycle. Future teams will be thankful for every piece of context that they can get, in order to “stand on the shoulders of giants”. You could say that the spec can avoid building up “knowledge debt” in the future organization by making a “knowledge deposit” when all of this knowledge is still fresh and on top of everyone’s minds.
The decision whether or not to make the spec a permanent record for the future is a fundamental tradeoff between speed now and in the future: Ensuring that the spec is consistent and complete today takes time and slows things down somewhat, but it will help future velocity by enabling learning from the past and avoiding research cycles. How you value current vs. future velocity depends on the stage of your company: If you are a startup that could not be around anymore in a year or two, you might not care about incurring knowledge debt by not codifying the lessons learned. A more mature company with a lot of built-up context, and a product that is a lot less simple and has a lot more history, probably values a few extra hours spent on making the spec a permanent record today way less than many team hours spent in the future on trying something that had failed before.
Specs are not a perfect artifact, nor should they aspire to be. Writing documents for documents’ sake is never a good idea. I do, however, believe that specs have multiple tangible benefits for product managers, teams, and companies, and will therefore continue to write them.
I hope this article was helpful. If it was, feel free to follow me on Twitter where I share interesting product management articles I come across daily.