Use this Job Story Template to Help Maintain Your Product Documentation | John’s Tips 2024W8
In this post, I introduce a software documentation review template that aims to enhance customer experience with accurate, timely product info that is customizable for multiple scenarios.
Here is the documentation review template I built that aims to help improve or maintain your customer experience with excellent documentation.
Good, up to date documentation for any product or feature is such hard art to get right, but taking away the pain of getting started is half the battle.
Customizable and automatable, this template can be adapted as a recurring task, story, or epic to align with each significant release, ensuring your documentation is always in sync with your latest features.
It acts not only as a guide but as a comprehensive index, directing engineers and designers to the documentation that matters most. The goal is to maximize your team's productivity, enabling them to focus on building stuff while minimizing the time spent trying to figure out what needs updating.
If you can save them a few days of pain trying to figure out what they need to update by simply setting up an automated ticket, it's a pretty good deal.
The ticket should be prioritised and refined just like any other task or epic, and baked into your regular planning. I’ve made the below format work for both a Platform and Feature team, just simply drop the words that you don’t need.
— Template —
Context
As we approach wide-scale adoption/release of our solution, it is crucial to conduct a comprehensive review of all customer-facing documentation that future adopters/customers may use during their (adoption) journey. This initiative/epic/task/story aims to ensure that the documentation is up-to-date, clear, and effective in guiding adopters/customers through the process of using our product. We will closely collaborate with our first adopters/customers to gather feedback and improve the documentation based on their experience.
List of Current Documentation:
1
2
3
4
Job Story #1
As the team responsible for maintaining the <name> infrastructure/feature, I want to ensure that all documentation intended for future adopters/customers is thoroughly reviewed and updated after our first adopter/customer completes their adoption process/uses the feature for the first time.
Acceptance Criteria
When conducting the review of infrastructure documentation, ensure that all documents are updated post-MVP launch to reflect any changes made since their initial creation, including design decisions that may affect the adoption process/customer journey.
When reviewing the documentation post-MVP go-live, reach out to our first adopter/customers to gather their feedback and identify areas for improvement. Incorporate their suggestions to enhance the clarity and ease of the adoption process for future adopters/customers.
When compiling the list of documentation to be updated, make sure to include all relevant documents from the provided list, ensuring that no critical documentation is missed in future reviews.
When reviewing the FAQ, avoid duplicating answered questions and instead provide direct links to the troubleshooting sections on the source readmes. This will ensure concise and efficient documentation.
When reviewing the documentation links, ensure that there are no unresolved comments on the Confluence pages created after the start date of this ticket, maintaining a clean and up-to-date documentation review process.
If time permits, review the new documentation structure for the domain and evaluate the feasibility of adding our own documentation to the domain’s page. Assess the effort required for integration, considering the potential benefits of centralizing the documentation.
By addressing these acceptance criteria, we will ensure that the documentation remains up-to-date, accessible, and valuable to future adopters/customers, facilitating a smooth and successful self-serve adoption experience.
For my past tips check out my past posts on Substack, go to my weekly list tip on Medium, or check out the hashtag #JohnsTipOfTheWeek on LinkedIn.