How to write good documentation: our top five best practices
Share on socials
How to write good documentation: our top five best practices
Holly Aspinall
1 November 2024
8 min read
Holly Aspinall
1 November 2024
8 min read
Jump to Section
Jump to section
What is documentation?
Why is good documentation important?
Four signs of bad documentation
Five best practices to improve documentation
Is your documentation up to scratch? Here’s how to identify and improve poor document management in your organisation.
Are you struggling to find information? Has your support team been flooded with requests for help? These are telltale signs your documentation isn’t doing its job.
Don’t worry! We’re here to help you identify the issues and put your documentation right with five straightforward best practices.
Don’t worry! We’re here to help you identify the issues and put your documentation right with five straightforward best practices.
What is documentation?
Documentation is essentially a collection of files and documents that help explain products, processes, or systems. The documents are usually stored or hosted online, so they're easily accessible to the users who need them.
Documentation comes in many forms and is used for many different purposes. You might have internal project documentation that's shared among team members, or external documentation such as a troubleshooting guide for customers.
Documentation comes in many forms and is used for many different purposes. You might have internal project documentation that's shared among team members, or external documentation such as a troubleshooting guide for customers.
Why is good documentation important?
Good documentation lays the foundations for success. It gives employees the guidance they need to get up and running quickly, helps customers self-serve information without overwhelming support teams, and allows leaders to track progress and make informed decisions quickly. But when your documentation is poor, everyone suffers.
So now you know why good documentation matters. But how do you spot bad documentation? And how do you fix it?
So now you know why good documentation matters. But how do you spot bad documentation? And how do you fix it?
Four signs of bad documentation
1. Information is out of date or hard to find
If you’ve found yourself or other team members pausing work to hunt down the latest information, you’re dealing with bad documentation.
Documentation needs to be easy to find and relevant, or it slows down processes and teamwork. In projects, for example, outdated or incomplete documentation can lead to delays and confusion as you have to continually verify and check information.
Documentation needs to be easy to find and relevant, or it slows down processes and teamwork. In projects, for example, outdated or incomplete documentation can lead to delays and confusion as you have to continually verify and check information.
2. Support tickets are rising (often about the same issue)
Bad external documentation can be confusing for customers to read (or impossible to find), so they seek out help rather than self-serving. If your support team is drowning under its workload, take some time to identify any common themes in its tickets. This will help you figure out whether there are gaps in your documentation or whether existing guides need improvement.
Poor documentation can lead to a surge in support requests
3. Knowledge vanishes without a trace
Any organisation's greatest asset is its knowledge. If information goes missing when an important team member leaves, it's a sign that you need to improve your documentation processes.
High-quality documentation is vital to ensure everyone can benefit from the experience and knowledge of others in an organisation and, of course, pass it along.
High-quality documentation is vital to ensure everyone can benefit from the experience and knowledge of others in an organisation and, of course, pass it along.
Learn more: What is institutional memory?
4. There's a constant cycle of duplication and déjà vu
Have you ever created a document from scratch, only to find that someone else did the same thing just a few weeks ago? You're not alone. According to the Global IIM Benchmark survey, a staggering 83% of global employees report having to recreate lost documents that already exist but can't be found.
Duplicating documents is a huge waste of energy and time that could be spent on something else - and it’s an unmistakable sign of bad documentation.
If you've read this far, maybe you've spotted some warning signs in your own documentation. If you’re ready to make a change, read on.
Duplicating documents is a huge waste of energy and time that could be spent on something else - and it’s an unmistakable sign of bad documentation.
If you've read this far, maybe you've spotted some warning signs in your own documentation. If you’re ready to make a change, read on.
How do you create good documentation?
1. Write for your audience
How you write your documentation depends on who the end user is. By defining your audience before you write, you can tailor the content to ensure it’s easy to understand.
For example, API documentation is aimed at developers, and therefore it can be more technical in language than something like a quickstart guide for customers.
Regardless of your audience, here are some rules of thumb to follow when writing:
For example, API documentation is aimed at developers, and therefore it can be more technical in language than something like a quickstart guide for customers.
Regardless of your audience, here are some rules of thumb to follow when writing:
- Keep unnecessary jargon to a minimum. When you have to include a term users may not be familiar with, use a tooltip to give extra context.
- Be concise, don’t ramble. Try to break information down into smaller paragraphs to make your content easier to follow.
- Don’t assume your reader knows everything. Remember to explain concepts that might be difficult to grasp, but only enough to help them follow your documentation.
- Where you can, illustrate points by using concrete examples. This will help readers to put the information into context.
2. Keep it consistent with a style guide
You likely won't be the only one contributing to your company documentation. By creating a style guide that outlines how documentation pages should look (and read), you can save time and effort upfront.
Standardising this process not only makes it easier for other team members to create and edit documentation, but also creates a smoother experience for users.
Here are some suggestions for what to include:
Standardising this process not only makes it easier for other team members to create and edit documentation, but also creates a smoother experience for users.
Here are some suggestions for what to include:
- Tone of voice
- Grammar and punctuation
- When/how to use acronyms and abbreviations
- Usage of images and diagrams
- Brand colours to include
3. Make documentation easy to find (and navigate!)
Documentation brings together all of your information in one place, but what good is it if nobody can find what they're looking for? Here are some ideas that can make documentation easier to find and search:
- When you create documentation, make sure everyone (customers or employees) has permission to view the pages.
- Group related topics together and use clear titles to help users navigate.
- Create a homepage for your documentation with clear, engaging links to other sections.
4. Update your documentation regularly
Your documentation is only helpful while it's still relevant. For internal documentation, updating your content reduces miscommunications and confusion among teams. This is particularly important for onboarding documentation because new hires are less likely to question this information.
Keeping your external documentation up-to-date allows customers to continue to find the answers they need, saving your support team time and effort. Remember to change your documentation before you release a new product update so customers won’t be confused.
Keeping your external documentation up-to-date allows customers to continue to find the answers they need, saving your support team time and effort. Remember to change your documentation before you release a new product update so customers won’t be confused.
💡 Tip: Include documentation updates as a task in future product communication plans to help keep information relevant.
5. Choose the right platform
This is the most important step! Choosing a tool built for documentation management will make everything else much easier.
What should you be looking for in a documentation management system?
What should you be looking for in a documentation management system?
- Scalability - whether you're a small business or a large enterprise, you should pick a tool that will scale with your needs. You never know how large your organisation might grow!
- Integration support - whether you want to add extra features to your documentation or save customers the effort of navigating to your support desk, it pays to have a platform that integrates with your favourite third-party tools.
- Collaboration support - maintaining documentation by yourself isn't easy. Pick a platform that makes collaboration easy, so you can coordinate updates and share knowledge quicker.
Confluence is a great platform for your documentation
✅ We recommend using a platform like Confluence for documentation because it ticks all of these boxes and much more. Confluence is easy to use (regardless of your skill level), secure, and lets you easily search and update page content. This means teams always have access to the latest information.
Take your documentation a step further
Tackling poor documentation doesn't need to be a headache. But while the right platform can make document management a lot easier, that's only half the battle - you still need to learn how to use it effectively.
If you work with Confluence, we can help you take your document management a step further. Ready to get started? Check out our six-step guide to creating better documentation in Confluence.
If you work with Confluence, we can help you take your document management a step further. Ready to get started? Check out our six-step guide to creating better documentation in Confluence.
Related Content
Read more
Written by
Holly Aspinall
Content Marketing Manager
As an experienced Content Marketing Manager, Holly is dedicated to writing valuable, accessible guides that help users understand their tools better and get more out of their workday.
LinkedIn →
LinkedIn →
Related Content
Read more