Product documentation can take many forms.
Tickets detailing new or modified behaviour provide a snapshot in time. Useful for teams to work from – but less helpful if you want to find it in future.
Project management tools, or ticketing systems, are not usually the best way to find how something works.
Instead, I prefer to write separate documents on Notion or Google Docs to capture how things work today – or how we want them to work in future. Here’s a quick structure you can use today.
The product document structure
- User story: The user story is often included in tickets to explain the what and why of a request. However, it’s also useful to go back and write down the user story for current functionality, to understand why it exists and if it’s still achieving its goal.
- Context: The user story should be quite short. If it’s helpful to include background details or supporting information, these can be included as part of the context.
- How to access / URL: Where to find this in a product navigation bar, and a URL to an example of the page. The best way to experience something is to try it for yourself!
- Screen: A screenshot of how the functionality looks today. For not yet created functionality, this could include wireframes or a UI design.
- Expected behaviour: The steps to go through to interact with the functionality, and the expected result.
- Comments and observations: For existing functionality, I like to test it out and note down any feedback. This can included gaps in functionality, errors, user feedback, questions, and potential improvements. For each piece of feedback, include the details, a category (such as the area of functionality, or things like “UI” / “Data”), and the impact (High/Medium/Low).
About testing products in this way
Because teams usually work from tickets, it may seem best to log all your feedback as tickets and let the team work from them there.
But by writing down the outcome of any testing in a document first, you give the team the opportunity to read your comments and think about possible solutions – rather than flooding them with tickets.
Teams may have a view on how to split up your feedback into tickets. A handful of small UI issues could be tackled in one ticket. Or the team may prefer smaller tickets so the work can be shared between a few people.
If there are big issues, this may be an indicator that functionality needs more time for improvements.
If you’re finding the same UI issues on every screen, perhaps some UI guidelines could be introduced so the team can work towards a baseline and minimise repetitive feedback.
Long-term documentation
Let’s say your product has a feature that sends a gift card to customers on their birthday – and the original request to do that work is on a single ticket.
In that situation, the ticket is one way to find out what was done and how the feature works – if you can find the ticket, that is.
Now imagine there have been several improvements to that feature since its launch.
The original ticket is no longer the source of truth. Instead, you’ll need to pick through multiple tickets, which could include additions, changes, and removals to the original request.
Tickets are now a much more cumbersome way to gain a complete picture of how the feature works.
Instead, writing a long-term product document is the better approach, as it gives you that single source of truth, and doesn’t require you to go and find a whole bunch of tickets.
Keeping things up to date
It’s important to keep product documents up to date. If the documents go out of date, it may seem that tickets are again the better place to find the latest status of a feature. But this seems like an excuse to not put in the time to create good documentation.
Take a product roadmap for instance. If it’s created and then nobody follows it, does it mean there’s no value in having a roadmap? Or should we be doing more every day to challenge why shiny new feature #55 appears to be in this week’s priorities when high value roadmap item #3 appears to have been forgotten about?
If we believe in the value of the roadmap, as Product Managers we should be mentioning it at every appropriate opportunity. If we find out something later on that may mean changing our focus, we can adapt if we feel it’s the right thing to pick up next.
In much the same way, if we believe in the value of product documentation, we should keep it up to date and remind people that we have it – along with why we have it.
