7 ways to make your public documentation more useful for users
Tips and advice to help you create great documentation, so you can improve your user ratings and reduce your support team’s load
Last updated
Tips and advice to help you create great documentation, so you can improve your user ratings and reduce your support team’s load
Last updated
Documentation is only useful if it’s up to date and people can find it. And when it comes specifically to public user documentation, this is even more essential. Missing or hidden information will frustrate your users, pushing them to contact your support channels or — even worse — complain on social media.
Worst of all, public docs aren’t easy. Getting them right is tough — but GitBook can help.
When you create your documentation with GitBook, readers can tell you how useful they’ve found a page using the page rating system. And with , you can quickly see the most and least popular pages in any published docs site.
But once you’ve identified your problematic pages, how can you improve that user score? Read on to get our top tips on upgrading your content and increasing user satisfaction.
While the advice below should help improve your content in general, it’s a good idea to pinpoint the pages that need attention before you get started. So first, let’s for your docs site.
To do this, head to your docs site and open Site settings. Then open the Features tab and enable the Page ratings option.
Well-organized content is easier to find, read and understand. So here are some quick tips to help improve your page organization:
Use subpages for related content – Subpages are great when you want to nest information inside another overarching page.
Put pages into groups – Once you’ve broken longer pages up into smaller pages and subpages, you can use page groups to collect them together and give them a title.
Studies have shown that short sentences are easier to read and understand. And removing unnecessary details helps keep your writing focused. So revisit your content with a strong focus on your goals — and cut unnecessary information. Be ruthless, and do whatever you can to make your pages simple and pertinent.
Once you’ve done that, read it all back through and add important information that was missing in the first place. You could insert code blocks, diagrams, or any other elements that might aid understanding. But do it all with that same level of focus in mind — so even the new content you add is applicable and useful.
Making your content more engaging can also help users — and improve their perception of your documentation.
The Insights panel does more than showing pages that need attention. They can also show you the pages your readers ranked highest. Take a look at those pages, analyze their layout and content, and try to work out what makes them work so well for your users. This may give you a valuable insight into what’s missing in your less-popular pages.
You can also see popular search queries in the Insights section of your site’s dashboard. Select the space you want from the drop-down in the top-right, then check the Search card to see popular searches — and how many results they had. You can also download the data as a CSV to get more detail.
You can use these search terms to understand what your users are looking for the most, or check a specific keyword using the bar at the top of the card. If a popular keyword doesn’t have much relevant content in your docs, add references to it in relevant places. And make sure you answer the kinds of questions people may ask about it.
Your support team know better than anyone what your users are struggling with — they hear about it every day! Speak to them about the most common questions they get. Then use that information to update your documentation and address those pain points.
This might highlight pages that need extra work. Maybe you just need to add or update an FAQs section that can address common queries. Either way, the insight is super valuable.
And if you’re both the documentation writer and the support team? Use the information you get from users to constantly tweak and improve your docs — then let them know you’ve done it. Maybe they’ll give the page a positive rating!
This one is by no means essential, but can offer you a lot more information about your pages and how they perform, from traffic to bounce rate and more. You can use a GitBook integration such as Google Analytics or Heap to connect an analytics platform to your docs in seconds.
Once it’s enabled, users will be able to rate the published page good, neutral or bad by scrolling to the bottom. You can see the results of these votes by opening your docs site’s dashboard and scrolling down to to view the Feedback section.
to read more about insights and page ratings.
Break up long pages – Pages with a ton of information are harder to scan, and make it tough for people to find the information they need. Instead, consider splitting information up into multiple pages, each with a dedicated focus. You can use to refer between them, if needed.
Use H1 and H2 headings – Break up content on your page by adding a H1 or H2 headings. These will appear in on the right of the screen, so users can click a title to jump straight to the information they want. You can also use H1, H2 and H3 titles as to direct people to a specific section on your page.
GitBook supports all kinds of dynamic elements in its block-based editor. So you can embed that let your users run tests right in your docs, as well as videos, drawings and more. You can even embed integration blocks right into the page, such as an interactive Node.js notebook, or a clickable walkthrough demo to show off a specific flow.
GitBook comes with a bunch of integrations built-in. And you can easily add more — or even , if you have something specific in mind.
