Why am I still writing Product Specification Documents?
and more importantly- why should you?
When I was learning to write the alphabet my grandfather gave me tasks to write the same letter over and over again till he decided it was legible. He used to grade every line of letters with a red pencil and correct my letters as if we were practicing for a calligraphy contest. I did not always enjoy these tedious tasks (though much love and attention was in them) and he used to recite to me that it does not matter that I can write if no one can read my writing.
My grandfather’s advice comes to mind whenever I am writing a document (I hardly handwrite anything nowadays, but it applies to content as much as it did to the lettering of it). I keep this advice in mind when writing Spec documents (product specification documents). Especially as I discovered over time these documents have several purposes and audiences.
Working with several development teams over the years I found that most of them do not like reading documents. Short or long, if it were possible to transfer the knowledge in another way, it was preferable for them. After experimenting with other methods s.a. wireframes, screen mocks, tables, flow charts and even just a conversation about it, I found myself going back to the Spec documents. So what is so great about these documents? and who am I writing these for?
The Product Manager
Your first audience for the Spec is you. You are your audience to begin with.
Writing the spec is an exercise in focus and clarity. Before I jot down what I want the feature or product to be I answer a few fundamental questions:
- Problem definition- what am I trying to solve? At this point I am also checking that I have the data to support that this is indeed a pain for my users. A gut feeling is not enough.
- Hypotheses of my solution- if I do X, Y will happen. This is important to define ahead of time and usually helps in identifying processes and funnels that our users go through. I can also identify at this stage which users will this solution affect and in which touch points.
- Impact estimation- what is the opportunity in this new feature? and how will we measure it? Should we A/B test this?
Don’t be fooled, these are not easy questions to answer, but they are mandatory to start the process. The answers help me identify at this early stage whether this is something worth investing in. I usually go back to answers after I finish the spec and revise them, but these are the guidelines before I dive deep into the planning.
Now is the time to roll up our sleeves and start getting into the nitty gritty of your feature. This is where we get into the happy flow, the main use cases and the edge cases you wish to tackle. If you write it well, you will manage to cover most use cases.
The Designer
If you are lucky enough to be working with your own designer and they are a good designer you probably aim your spec to be detailed enough so the designer can understand what the flows of the feature are but not too detailed so the designer will be left with the task of “adding colour” to your wireframes. Your spec should be the instruction manual for the designer so they will be able to turn it into the screens or components to be implemented in your product.
The Developers
As we mentioned before, I can generalise that developers are not big fans of written documents. What they do like however is clarity. The design by itself cannot answer all the questions that may rise (how many characters are in this field? what would happen if the user switches to a different currency? are just a few of the questions the spec can help answering).
While the design can serve as a ‘picture menu’, the developers need to know all the ingredients, and this is what the spec should cover. It should be clear in describing the user journey and this sometimes means you should add flow charts, internal sections and breakdowns of the behaviour and anything that could make it readable. I once knew a product manager that used to hide easter eggs in her specs, to check whether the team has read it. I do think this is taking extreme measures as the purpose is not that the Dev team can create a book report on your spec, but rather that it would be the source of answers to their questions, but it did work for her and her development team found it playful.
The Future Team
In a few weeks or months or longer someone may encounter a weird behaviour in your product. They may reach out to you and ask whether it was meant to be this way (is it a bug or a feature?) but by that time you may have moved to a different team, maybe the whole team has changed or maybe like me, you simply have very bad memory. If your spec is comprehensive this is the right time to dust it off and reopen it as it can serve as the source of truth. This is where you wrote down what you intended this feature to do.
It would also help with knowledge transfer to new team members and assist other teams who want to integrate with your feature to know what the intended behaviour is.
The Dynamic Spec
The spec is your directing guide to planning the feature, the guideline for the designer, the recipe for your development team and your source of truth for future questions. As such it is also dynamic- it evolves as your knowledge of your feature expands. After each review of the feature with your team you may have some additional data to add to it — that one more edge case you didn’t think of will be added, that component that is actually impossible to build with reasonable effort would be deleted.
It is not easy keeping track of all these changes and I recently learned from a great Product Manager that keeping a versioning table of these changes can be a great guide to navigating this ever-evolving spec.
If you keep in mind the different target audience of your spec you will also be sure to keep it concise and easy to digest. Be critical with your editorial cuts- eliminate unnecessary steps, make sure the structure is easy to follow (sections and titles can make a huge difference) and add the occasional flow chart where it can alleviate doubts. But mainly, don’t give it up. Its values are worth the effort it takes you to write it and others to read it. And keep my grandfather’s advice in mind- think of your readers when writing it.
