I don’t know about you but I HATE instruction manuals. When I bought a new car recently, I just wanted to drive the thing. The user manual could stay where it belonged: the glove compartment.
But like an umbrella on a rainy day, product documentation is there when you need it. Like when my wife and I couldn’t work out how to use our new car’s infotainment system and the manual saved us ripping it out and stomping on it.
But product documentation that doesn’t tell you how to do what you want to do is the same as an umbrella that’s full of holes. So in this article, we’ll look at seven product documentation best practices to make sure your users get what they need (and don’t rip out your app and stomp on it 😉).
What is product documentation?
Product documentation comprises all the documents that help a user understand a software product’s purpose and functionality.
It includes technical specifications about the product and its features, user guides with step-by-step instructions on how to do something, and troubleshooting information. It can also include use cases and examples to help users understand the product’s context.
You may also find FAQs providing information on common questions and concerns customers have; a roadmap listing new features and improvements that are being worked on; and release notes communicating information about any changes or updates to the software.
Why is product documentation important?
The Agile Manifesto prioritizes “working software over comprehensive documentation”. After all, the manual’s no good if the car doesn’t run. Making the car is obviously more important.
However, some software providers misinterpret this as implying that they can release apps without any supporting documentation. That means they obviously didn’t read the disclaimer immediately below the four values in the Manifesto:
“While there is value in the items on the right, we value the items on the left more.”
What the writers of the Agile Manifesto were trying to emphasize was: don’t rely on your product documentation to make your software usable. All software should be intuitive and user-friendly. Really, it should be plug-and-play. That’s certainly what I want. When I download an app, I want to use it immediately. The last thing I want to do is learn how.
The purpose of product documentation is to help users understand the software better, get more value out of it, and find solutions when something breaks or you’re not sure how to do something. Without it, users could become frustrated with your software and uninstall it.
7 product documentation best practices
The following product documentation best practices will help you create software documentation that is useful, easy to understand, and enables customers to maximize the value they get from your software.
1. Think carefully about structure, navigation, and design
If you want people to use your product documentation, you need to offer a good user experience, namely a structure, navigation, and on-page design that are intuitive and engaging. Design can offer clarity that words sometimes can’t.
Choose a platform that allows customers to explore your documentation but also search immediately for what they need. For instance, Confluence has a page tree menu, a search bar, and it’s a wiki, rich with links to other pages so that users can explore content easily. You can enhance the look and readability of each Confluence page using page templates and macros such as panels, dividers, and tables of contents.
You can also use Atlassian Marketplace apps like Spacecraft to enhance your design, structure, and navigation further. Spacecraft allows you to customize your Confluence spaces with themes, custom fonts, and easy-to-remember URLs. It also lets you remove native Confluence elements such as authors, comments, and the last-modified date, so that your documentation looks less like Confluence and more like a unique website.
2. Create documentation page templates to maintain consistency
Once you have decided on a structure and format for your documentation pages, create a template for your documentation writers to follow. That way, all your pages are consistent in look and readability, which in turn makes your documentation more professional and credible. Best of all, they’re quicker and easier to create.
In Confluence, you can create page templates with a specific set of macros, e.g. panels, tables, labels, and bulleted lists. Confluence also comes with a range of page templates, such as for a how-to article and a product roadmap, which you can adapt to fit your requirements.
3. Keep your language simple and understandable
Your product documentation is for end users. Unless they happen to be software developers or IT professionals themselves, they’re likely to be non-technical users who just want the software to work without having to study computer science.
So keep your language simple and understandable and avoid technical jargon at all costs. This includes an absolute favorite of the tech world: acronyms. Only a few acronyms, like IT and AI, can be used without explanation. Any others should be kept to a minimum and, at the very least, need defining the first time you use them.
A good tip when writing your product documentation is to treat your readers as though they know how to use a computer, and that’s it.
4. Use screenshots frequently, and annotate them
When writing step-by-step how-to articles, add as many in-app screenshots as possible. This makes it easier for customers to know where they’re clicking. Make instructions even clearer by marking up images with lines, boxes, and arrows.
Video demos and GIFs are also really helpful, and make your documentation more engaging.
5. Include examples and use cases
Examples and use cases help customers understand the proper application of your product and its features. They’re also useful for showing customers how to use a product in a way they haven’t thought of, thereby extracting more value from it.
You could also include references to existing customers in your examples, demonstrating how they are using your product and how it’s meeting their goals.
6. Choose the right documentation tool
The best tool for creating product documentation is one that makes your information more accessible, shareable, and consumable.
With Confluence, there are features and optional add-ons designed to help you capture, distribute, and update technical product documentation. Its benefits include:
- Tree-like page hierarchy structure AND a wiki-style system of links for optimal and intuitive navigation
- Easy to create relationships between content with links and labels, and the content by label automatically adds related content to pages for cross-referencing
- Highly collaborative in the drafting phase thanks to comments, @mentions, reactions, and automatic notifications of any changes
- Comes with page templates and the ability to add your own
- Lots of layout and formatting options, including tables, columns, lists, and dividers
- Content options for making pages more digestible, such as the table of contents macro, and the tip, note, info, and warning panel macros
- Easy to embed multimedia content such as videos and images
- Lets you reuse content from one page on other pages, using the excerpt include macro (adds an excerpt) and the include page macro (adds a whole page)
- Full page history helps keep track of changes easily
- Can be adapted and customized thanks to lots of helpful apps such as Spacecraft and Aura
7. Continually update your product documentation
Our final product documentation best practice is creating a maintenance calendar and conducting regular audits of your documents. Every time there is a product update, you also need to update the document. If you work in Jira, consider adding a subtask for updating documentation to every release, and linking to the documentation page in the Jira issue.
Improvements to usability and existing features mean that the pages dedicated to those will need new screenshots and explanations. Make sure you check for duplicate content and content that is no longer relevant, otherwise your end users could act on the wrong information.
Software moves at such a fast pace that keeping documentation updated is a challenge. Even the major platform providers still have old documentation lying around in the ether. But all it does is confuse the user. And if it’s doing that, it’s no longer serving its primary purpose.
A real-life product documentation example
Here is some product documentation for Templating.app. You can see that the documentation is organized into four main categories. The first three are the main functions of the product: creating project, issue, and subtask templates in Jira. Within those categories there are subcategories that take the user on a step-by-step journey through the functionality.
Each documentation page follows a similar template that includes an annotated screenshot slideshow at the top of each page, generated using the AI-powered documentation creation tool Scribe. Then there are text instructions beneath.
This documentation was created in Confluence and leverages many of its signature features such as embedded videos, info panels, and tables of contents.
You’ll notice it doesn’t look much like Confluence and that’s because it’s been turned into a Spacecraft website. So it has a custom background, custom menus, a unique subdomain, and various aspects of native Confluence hidden.
Want to share public Confluence documentation spaces with a customized theme, creating a more engaging and branded experience for your customers? Book a personal demo of Spacecraft or download Spacecraft for free for a month on the Atlassian Marketplace.
To summarize (TL;DR)
- All new products should be released with accompanying product documentation.
- Product documentation helps users understand your software better and get more value out of it.
- Make sure your documentation has a structure and navigation that is intuitive, simple, and enables users to find what they need easily and quickly.
- Product documentation should contain simple language and lots of screenshots.
- Provide use cases and examples to demonstrate how your product can be used.
- Keep your documentation up to date.
- Confluence is a popular choice for creating product documentation because of the page tree structure, wiki-style links, rich collaborative features, page templates, and formatting and content options for making documentation more readable and engaging.
- Confluence documentation sites can be adapted and customized using apps like Spacecraft, which turns public Confluence spaces into themed and branded websites and allows you to hide native Confluence elements.
- Spacecraft: The New Way to Theme your Public Confluence Spaces
- Documentation from Jira to Confluence – How It Works with Autopage!
- Bringing Style to Your Confluence Space
- Aura – How To Build a Stunning Landing Page with Confluence Cloud
