7 tips to make your public documentation more useful for users
Tutorials & tips
Tutorials & tips
Tutorials & tips
Tutorials & tips
25 Jan 2024
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 our built-in Insights panel, you can quickly see the most and least popular pages in any published docs.
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.
First, switch on page ratings
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 switch on page ratings for your published documentation.
To do this, head to the published space and hit Customize. In the menu, click on the Configure tab, then enable the Page Rating option.
You can enable page ratings for your published space by opening the Customize menu, selecting the Configure tab, and toggling the setting on.
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 the Insights page from the sidebar, and choosing the Content scores tab.
Head to our documentation to read more about insights and page ratings.
7 tips for improving your product documentation
1. Consider your content structure
Well-organized content is easier to find, read and understand. So here are some quick tips to help improve your page organization:
Break long pages up – Pages with tons 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 relative links to refer between them, if needed.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.Use H1 and H2 headings – Break up content on your page by adding a H1 or H2 headings. These will appear in the page outline 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 anchor links to direct people to a specific section on your page.
2. Edit and re-edit your text
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.
3. Add interactive content
Making your content more engaging can also help users — and improve their perception of your documentation.
GitBook supports all kinds of dynamic elements in its block-based editor. So you can embed videos, and include example code or API information. 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.
Interactive blocks, such as an interactive, annotated demo, can help add extra context or walk users through a complex process.
GitBook comes with a bunch of integrations built-in. And you can easily add more — or even build your own, if you have something specific in mind.
4. Use successful pages as inspiration
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.
5. Analyze search queries
You can also see popular search queries in the Insights panel. Open the Search analytics tab and select your space to see popular searches — and how many results they had. You can also download the data as a CSV to get more detail.
In the Insights panel you can view the most popular searches in your space, and how many results each one returned.
You can use these search terms to understand what your users are looking for the most. If a chosen keyword doesn’t have many results, add references to it in relevant places. And make sure you answer the kinds of questions people may ask about it.
6. Talk to the support team to get more details
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!
7. Set up deeper analytics
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.
→ Read the insights documentation
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 our built-in Insights panel, you can quickly see the most and least popular pages in any published docs.
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.
First, switch on page ratings
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 switch on page ratings for your published documentation.
To do this, head to the published space and hit Customize. In the menu, click on the Configure tab, then enable the Page Rating option.
You can enable page ratings for your published space by opening the Customize menu, selecting the Configure tab, and toggling the setting on.
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 the Insights page from the sidebar, and choosing the Content scores tab.
Head to our documentation to read more about insights and page ratings.
7 tips for improving your product documentation
1. Consider your content structure
Well-organized content is easier to find, read and understand. So here are some quick tips to help improve your page organization:
Break long pages up – Pages with tons 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 relative links to refer between them, if needed.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.Use H1 and H2 headings – Break up content on your page by adding a H1 or H2 headings. These will appear in the page outline 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 anchor links to direct people to a specific section on your page.
2. Edit and re-edit your text
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.
3. Add interactive content
Making your content more engaging can also help users — and improve their perception of your documentation.
GitBook supports all kinds of dynamic elements in its block-based editor. So you can embed videos, and include example code or API information. 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.
Interactive blocks, such as an interactive, annotated demo, can help add extra context or walk users through a complex process.
GitBook comes with a bunch of integrations built-in. And you can easily add more — or even build your own, if you have something specific in mind.
4. Use successful pages as inspiration
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.
5. Analyze search queries
You can also see popular search queries in the Insights panel. Open the Search analytics tab and select your space to see popular searches — and how many results they had. You can also download the data as a CSV to get more detail.
In the Insights panel you can view the most popular searches in your space, and how many results each one returned.
You can use these search terms to understand what your users are looking for the most. If a chosen keyword doesn’t have many results, add references to it in relevant places. And make sure you answer the kinds of questions people may ask about it.
6. Talk to the support team to get more details
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!
7. Set up deeper analytics
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.
→ Read the insights documentation
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 our built-in Insights panel, you can quickly see the most and least popular pages in any published docs.
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.
First, switch on page ratings
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 switch on page ratings for your published documentation.
To do this, head to the published space and hit Customize. In the menu, click on the Configure tab, then enable the Page Rating option.
You can enable page ratings for your published space by opening the Customize menu, selecting the Configure tab, and toggling the setting on.
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 the Insights page from the sidebar, and choosing the Content scores tab.
Head to our documentation to read more about insights and page ratings.
7 tips for improving your product documentation
1. Consider your content structure
Well-organized content is easier to find, read and understand. So here are some quick tips to help improve your page organization:
Break long pages up – Pages with tons 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 relative links to refer between them, if needed.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.Use H1 and H2 headings – Break up content on your page by adding a H1 or H2 headings. These will appear in the page outline 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 anchor links to direct people to a specific section on your page.
2. Edit and re-edit your text
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.
3. Add interactive content
Making your content more engaging can also help users — and improve their perception of your documentation.
GitBook supports all kinds of dynamic elements in its block-based editor. So you can embed videos, and include example code or API information. 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.
Interactive blocks, such as an interactive, annotated demo, can help add extra context or walk users through a complex process.
GitBook comes with a bunch of integrations built-in. And you can easily add more — or even build your own, if you have something specific in mind.
4. Use successful pages as inspiration
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.
5. Analyze search queries
You can also see popular search queries in the Insights panel. Open the Search analytics tab and select your space to see popular searches — and how many results they had. You can also download the data as a CSV to get more detail.
In the Insights panel you can view the most popular searches in your space, and how many results each one returned.
You can use these search terms to understand what your users are looking for the most. If a chosen keyword doesn’t have many results, add references to it in relevant places. And make sure you answer the kinds of questions people may ask about it.
6. Talk to the support team to get more details
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!
7. Set up deeper analytics
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.
→ Read the insights documentation
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 our built-in Insights panel, you can quickly see the most and least popular pages in any published docs.
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.
First, switch on page ratings
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 switch on page ratings for your published documentation.
To do this, head to the published space and hit Customize. In the menu, click on the Configure tab, then enable the Page Rating option.
You can enable page ratings for your published space by opening the Customize menu, selecting the Configure tab, and toggling the setting on.
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 the Insights page from the sidebar, and choosing the Content scores tab.
Head to our documentation to read more about insights and page ratings.
7 tips for improving your product documentation
1. Consider your content structure
Well-organized content is easier to find, read and understand. So here are some quick tips to help improve your page organization:
Break long pages up – Pages with tons 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 relative links to refer between them, if needed.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.Use H1 and H2 headings – Break up content on your page by adding a H1 or H2 headings. These will appear in the page outline 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 anchor links to direct people to a specific section on your page.
2. Edit and re-edit your text
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.
3. Add interactive content
Making your content more engaging can also help users — and improve their perception of your documentation.
GitBook supports all kinds of dynamic elements in its block-based editor. So you can embed videos, and include example code or API information. 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.
Interactive blocks, such as an interactive, annotated demo, can help add extra context or walk users through a complex process.
GitBook comes with a bunch of integrations built-in. And you can easily add more — or even build your own, if you have something specific in mind.
4. Use successful pages as inspiration
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.
5. Analyze search queries
You can also see popular search queries in the Insights panel. Open the Search analytics tab and select your space to see popular searches — and how many results they had. You can also download the data as a CSV to get more detail.
In the Insights panel you can view the most popular searches in your space, and how many results each one returned.
You can use these search terms to understand what your users are looking for the most. If a chosen keyword doesn’t have many results, add references to it in relevant places. And make sure you answer the kinds of questions people may ask about it.
6. Talk to the support team to get more details
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!
7. Set up deeper analytics
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.
→ Read the insights documentation
Get the GitBook newsletter
Get the latest product news, useful resources and more in your inbox. 130k+ people read it every month.
Similar posts
Create, search and manage your knowledge at scale. Effortlessly.
Create, search and manage your knowledge at scale. Effortlessly.
Create, search and manage your knowledge at scale. Effortlessly.
Create, search and manage your knowledge at scale. Effortlessly.