Thoughts on product documentation
Jira cards, templates, slides - what to use and when?
As someone who likes to think strategically about why things need to be worked on at all, I’ve always enjoyed working on longer-form documents that go into greater detail about the purpose behind features being built. But admittedly, each time I need to start a document, I ask myself, “What is the most efficient and effective way to do this?” Below I’ve outlined what I use to document what in the time I’ve spent in product management.
Before we dive in, like this post or leave your email address in the comments below and I’ll email you some templates that I use in my day-to-day role! Note that I’ll be sending out exclusive content to these individuals in the future as well.
One pagers
This is a document that is used to outline the business case of a feature. Why are we building it, what are the high level requirements that will need to be implemented to satisfy the primary use cases, and what are the KPIs associated with the feature? This is a brief document that I write up in a Google Doc, and it’s essential to get buy-in from all stakeholders (executives, sales, CS and engineering teams). Of course, you want to research competitors and conduct customer surveys as you ultimately finalize the high level requirements. Once this document is finalized, you can move on to the next phase of the product development process. I outline those phases in part 4 of my post here.
Miro
Miro is a great tool for visually mapping flows and customer journeys. I’ve used Miro to assist with:
Figuring out all the pathways users take to perform an action in the product
Developing a great UX for a new feature
Troubleshooting a bug or customer problem
A piece of advise I have for using tools like these is to really be thoughtful about when it would actually be helpful to use. Visual tools are fun to use and engaging to audiences, but they take time and should only be used deliberately.
Product Requirements Documents (PRDs).
As I mention above, I enjoy strategic thinking, which usually goes hand in hand with longer-form documentation. I used to write PRDs in a way that would combine the details of “why are we working on this?” with the actual product requirements. What I learned is that the document just got too long and confusing. Certain stakeholders also don’t need to look at PRDs — requirements can get technical and if there’s no action I need from our head of sales or CS, for instance, they just don’t need to spend time looking at them.
PRDs are a great way to get your own head on straight before you ask engineers to dive head first into feature development. Yes, they outline requirements, but their purpose is provide alignment. They provide an overarching context around how epics relate to each other, how much work is involved with each epic, and how the UI fits together (Figma comes into play here, but that’s more of a design tool than a PM tool). There are various templates out there (like this page or leave a comment below to receive a template I use), but the best ones to use ultimately come down to what is most helpful for creating alignment with engineering, design and the PM.
One very important thing I want to say about PRDs and any other longer-form documentation: it is your responsibility as the PM to communicate the document’s purpose and encourage other team members to provide more context (if necessary) and ask questions about it. I have learned that it can be difficult for folks to truly read through these documents as it is easier to merely read over Jira cards to know what work you actually have to do in a sprint as an engineer. But PRDs can get teams aligned earlier on and are worth the investment if people take the time to read them. Of course, try to be as brief as possible as the owner of the document.
Jira cards
PMs are not the only people writing Jira cards. Bugs, features and engineering initiatives are all laid out in Jira. In my company, members of customer support tend to write the Jira cards for any smaller feature requests or bugs that might arise in the product. Engineering leads tend to write cards about engineering initiatives (deeply technical cards with ideas for how to improve security or performance). PMs write feature card specs.
These cards are an art and a science. The cards should be detailed enough to spark questions from engineering. They should be easy to read and organized. If an engineer is out sick one day, the card should be able to be reassigned to someone else and that person should have a crystal clear idea of what needs to be accomplished just be reading the card.
Slides
Finally, I use Google Slides for release planning, competitive analysis, and GTM documentation.
Release planning most importantly includes an easy to read grid outlining what functionality will be available in which release version. I go more into how that is figured out and presented in part 3 here.
For competitor research, the exact criteria I present does vary on the feature. However, these slides almost always include pricing information, key value propositions / differentiators, and anything competitor solutions are missing that our customers might find valuable.
GTM documentation is typically presented in several slides, and includes an FAQ (which is then later stored in Confluence for the entire organization to view at any time), key talking points for our CS and sales teams as they interact customers, marketing timelines and strategy, pricing information and success metrics.
