Introduction

Documentation can have a major impact on the success of your users, so much that some have described documentation as an extension of the product itself. Providing self-serve resources for users to complete setup instructions, find answers to their questions, and troubleshoot any issues they encounter is crucial to helping them succeed. But what does “success” look like with docs? 

As docs writers at Heap, we’ve spent a lot of time figuring out how to use our own product to make sure our docs are as helpful as they can be. In the process, we’ve created this how-to guide to share the best of what we’ve learned with our fellow docs writers.

This guide is a labor of love from our docs team to yours. If you have questions, feedback, or ideas to make this guide better, feel free to click the “Was this article useful” buttons on the side, or reach out to us directly via docs@heap.io. We’re grateful you took the time to read our docs, and we’re always here for all of your Heap docs needs.

Step 1: Create baseline events & properties

To set up the charts in the rest of this guide, you’ll first need to make sure the following events, snapshots, and segments are set up in your account. We’ve provided examples of how these are defined in our Heap account here at Heap (which we lovingly refer to as “Heap on Heap”).

The names are examples from our own Heap account that use our naming convention best practices. We’ll be referring to these examples throughout this guide. Feel free to name yours whatever you want, as long as it’s easy for your team to recognize!

For steps to create any of these data types, see the following:

• Events: see our visual labeling guides by platform and How to create events
• Snapshots: see Capture Search Queries via snapshots for steps to create the specific snapshot referenced in this guide
• Segments: see the Creating Segments section of the segments overview guide

Properties: see How to create new labeled properties

Name	Description	Definition
View – Any doc page	An event for any view of any page of your doc site.	View, where domain equals help.heap.io (replace this with your docs site domain!)
Click – Docs table of contents	An event for any click on any item in a docs table of contents.	Click on .nav-toc (this varies based on your CSS)
Click – Docs search bar	An event for any click on your docs search bar.	Click on .search-bar (this varies based on your CSS)
Submit – Docs search	An event for when a user submits a search in your docs site search bar.	Submit on .search-form (this varies based on your CSS)
Submit – Docs search (no results)	An event for when a user submits a search in your docs site search bar, and there are no results.	Submit on .search-form.no-results (this varies based on your CSS)
View – Any app page	An event for when a user visits any page of your app.	View, where domain equals heapanalytics.com (replace this with your app domain!)
Search term	A snapshot property for search terms used on your docs site.	Snapshot property defined on Submit – docs search*
Internal users	A segment to filter out internal employees.	Identity contains heap.io See Internal users for steps to set this up
Bots	A segment to filter out bots.	Initial IP address equals 12.345.67.890 See Bots for steps to set this up

If you’re using our identify API to track user identity, you can also use the identity info being sent into Heap to dig into any of the charts below, such as looking up which users visit your docs the most often.

Step 2: Analyze your docs UX

Now that your data types are set up, we’ll cover what charts you should create to understand general usage and identify opportunities to improve your docs.

Chart 1: Pageviews per month

As a baseline for tracking overall docs traffic, we recommend starting with a chart of monthly pageviews from over the past year.

Steps to set this up:

1. Navigate to Analyze > Usage over time
2. Make sure Total events is selected at the top
3. In the event drop-down, select your View – Any doc page event (created in step 1)
4. Select date range – past year (or whichever date range you’d like to see!) grouped by Month
5. Optional: Add filters to filter out internal users and bot traffic
6. Click View results to create this chart!

Your chart should be set up like this:

Select line chart from the chart type drop-down to see a visual representation of your docs site traffic month-by-month.

What does this tell you?

This gives you a high-level sense of general traffic patterns throughout the year, compared month-by-month. 

How to interpret?

Ask yourself how these traffic patterns align with other metrics or with behavior patterns. Do you notice spikes in traffic from a large product or marketing release? Are there dips during your users’ holiday seasons?

Starting with a baseline of your general traffic will be useful for contrasting with results from the next few charts.

Chart 2: Average pageview per user

Once you have a sense of how many overall views your docs are getting, it’s helpful to dig into the average views per user.

Steps to set this up:

1. Navigate to Analyze > Usage over time
2. Select Average per user at the top (you may need to click More options…)
3. In the event drop-down, select your View – Any doc page event (created in step 1)
4. Select date range – past year (or whichever date range you’d like to see!) grouped by Month
5. Optional: Add filters to filter out internal users and bot traffic
6. Click View results to create this chart!

Your chart should be set up like this:

What does this tell you?

This shows you the average number of docs pageviews per user, including your homepage, category pages, individual docs, search result pages, tag pages (if you have those) and any other pages. The date range gives you insight into spikes and trends for these pages.

How to interpret?

Are you seeing lots of users looking at one doc, or fewer users looking at more docs? You can compare this with the data in your Pageviews per month chart to get a better understanding of the actual size and engagement level of your user base.

Chart 3: Pageviews per month grouped by Path

To see your most viewed pages, take your Pageviews per month chart, click the + Add group by button, and select the Path property.

What does this tell you?

This will show you the most popular pages of your docs site(s), including your homepage, category pages, individual docs, search result pages, tag pages (if you have those) and any other pages. The date range gives you insight into spikes and trends for these pages.

How to interpret?

Keeping track of your most popular docs and pages is useful in a variety of ways depending on the traffic patterns you are seeing and the types of docs. Spikes in traffic for a particular doc can be a sign of positive interest, such as an increase in interest in a feature that the doc is about, or negative interest, such as an increase in views of a troubleshooting guide after an outage.

The best way to make use of this data is to compare it to other data points you have access to. For example:

• Compare feature doc views to in-app feature usage to see if they match. If they don’t, there might be a discoverability issue with the doc, or a usability issue with the feature.
• Compare troubleshooting doc views and support write-ins to see if the most common support topics are effectively covered by your docs.
• Compare marketing campaigns to docs that correlate to that marketing content to see if marketing drove users to want to learn more.

We recommend trying out a variety of group bys based on your typical audience, such as grouping by Location to see if it aligns with where your users are based. You can also try out different date ranges to see how traffic fluctuates per week, day, or even per hour. 

Chart 4: Most-clicked sections of table of contents

We’ve found the best way to measure engagement within a doc is to look at clicks on section titles in the table of contents. To measure this, set up the following chart:

1. Navigate to Analyze > Usage over time
2. Make sure Total events is selected at the top
3. In the event drop-down, select your Click – docs table of contents event (created in step 1)
4. Add two group bys: one for Title, and one for Target Text
5. Select date range – past year (or whichever date range you’d like to see!) grouped by Month
6. Optional: Add additional filters to filter out internal users and bot traffic
7. Click View results to create this chart!

Your chart should be set up like this:

What does this tell you?

This will show you the most-clicked headers for each of your docs. You can play around with the date range for additional insight into spikes and trends of these clicks, and look at the total column at the very right side of the table view to see overall clicks.

How to interpret?

The most popular sections of docs can influence how you decide to structure your content. For example, if the fifth section of a ten-section guide is overwhelmingly the most-clicked header, it might make sense to pull that section out into its own doc to make it more discoverable, or move it up the page.

Chart 5: Search experience conversion

Search is the #1 most-completed action on most docs sites (and is often the very first action taken). It’s important to make sure your search is performing as expected so you can make a good first impression.

We’ve found that tracking conversion throughout the search funnel helps us measure if site changes are impacting our search UX. To track this, set up the following chart:

1. Navigate to Analyze > Funnel
2. In the steps drop-downs, add the following steps in this order (created in step 1):
   1. View – Any doc page (assuming your search bar is present on all pages)
   2. Click – Docs search bar
   3. Submit – Docs search (use the + icon to add additional funnel steps)
3. Optional: Add additional steps based on how your search UX is designed (for example, we might add a Click – top 5 search results event because of how our search experience is set up).
4. Select date range – the entire range (or whichever date range you’d like to see!) grouped by Month
5. Optional: Add additional filters to filter out internal users and bot traffic
6. Click View results to create this chart!

Your chart should be set up like this:

What does this tell you?

This will show you the conversion rate between each step of your funnel, which is the percentage of users who complete the next step after the first step. 

If you have session replay, you can watch replays of users dropping at this point (not completing the next step) by clicking the Replays of users dropping button beneath each step.

How to interpret?

The very best way to understand why users might not be completing each step is to watch the replays between steps and look for patterns. Perhaps there’s a step in between that may be worth adding to your funnel, or something else in the UX is pulling them away from completing their search. 

The funnel chart type provides a variety of useful tools for digging deeper into your results, such as: 

• Scroll down to the Effort Analysis section for additional info about step conversion, such as the time spent on each step and the revisit rate.
• Click on the Top Events tab to see common actions taken between the steps of your funnel, which may provide additional insight into the overall search UX. 
• Use Path Comparison to compare the current flow to an alternative one, such as if users were to click on something else before completing their search.
• Keep an eye on the Next Steps section on the side, which will suggest hidden paths or group bys that you may want to explore based on your results.

All of these will help you better understand your current search UX and where improvements can be made. For more information on all the cool things you can do with funnels, see Funnel analysis overview.

Chart 6: Most common search terms

With search being such a popular way to find information, keeping track of your most common search terms will help you better understand your users’ needs, and spot unusual spikes that might be insightful for your team. To track this, set up the following chart:

1. Navigate to Analyze > Usage over time
2. Make sure Total events is selected at the top
3. In the event drop-down, select your Submit – Docs search event (created in step 1)
4. Add a group by for your Search term property (created in step 1)
5. Select date range – past year (or whichever date range you’d like to see!) grouped by Entire range
6. Optional: Add additional filters to filter out internal users and bot traffic
7. Click View results to create this chart!

Your chart should be set up like this:

What does this tell you?

This will show you all of the most popular search terms in your docs, ordered by how many times they were searched for. Hover over any result to see the exact count. These are also listed out in a table directly below the bar chart, with the total count of searches at the end.

How to interpret?

Search terms are the best way to get insight into users’ motives for visiting your docs in the first place. Searches for feature names may indicate that users want to learn more about those features, whereas searches for error messages, unsupported platforms, and other terms are all useful feedback on where you can provide context in docs to help users who are stuck or confused move forward.

Our docs team regularly double-checks the search experience for our most popular terms by entering them into search and seeing what comes up in the top 5 results. If it’s what we expect and want users to find, we leave it be. However, if a useful doc is being buried by other, less relevant docs, we adjust our SEO accordingly. Use the info from this chart to walk in your users’ shoes and calibrate as needed to provide best search experience possible!

Chart 7: Searches with no results

One of the best ways to identify opportunities to fill gaps in your docs (and product feedback to share internally) is to track search terms from searches that yielded no results. 

To do so, set up the following chart (it’s exactly the same as your ‘Most common search terms’ chart, just with your no results event instead):

1. Navigate to Analyze > Usage over time
2. Make sure Total events is selected at the top
3. In the event drop-down, select your Submit – Docs search (no results) event (created in step 1)
4. Add a group by for your Search term property (created in step 1)
5. Select date range – past year (or whichever date range you’d like to see!) grouped by Entire range
6. Optional: Add additional filters to filter out internal users and bot traffic
7. Click View results to create this chart!

What does this tell you?

This will show you the most common search terms where there is currently no result, ordered by how many times it was searched for. Hover over any result to see the exact count. These are also listed out in a table directly below the bar chart, with the total count of searches at the end.

How to interpret?

These results often end up being a mix of product feedback, potential docs improvements, and spam/bot submissions. In the image above, most of the results are spam, though the search for rudderstack (a platform we don’t currently have an integration with) is good product feedback, and the search for spotlight (a feature we renamed later) is an opportunity to update our docs to make sure the old feature name points to the doc on the renamed feature.

We recommend evaluating these regularly for opportunities to update docs content to meet search needs, share product feedback with your team, and apply filters to exclude bot traffic if it’s consistently coming from certain IPs.

Chart 8: Journeys to and from docs

The very best measurement of a successful doc is when a user reads a doc and then goes on to complete the steps that the doc was describing. To measure this, set up the following chart:

1. Navigate to Analyze > Journeys
2. Make sure User journey is selected
3. Make sure the “What percentage of users who” drop-down is set to started
4. In the event drop-down, select your View – Any doc page event (created in step 1) or filter for a specific doc that you’d like to measure this for
5. Click the + Add step button, then select an event that represents completing a task in your app (for this example, we’ll use View – Any app page to get a general baseline of users who go from docs to in-app)
6. Select date range – past year (or whichever date range you’d like to see!) grouped by Entire range
7. Optional: Add additional filters to filter out internal users and bot traffic
8. Click View results to create this chart!

Your chart should be set up like this:

What does this tell you?

The results will show you the percentage of users who completed step 2 immediately after step 1. To see other paths, click the + Explore other paths button. This will bring up a list of actions users took instead of step 2, as shown in the screenshot below.

In our example, we notice 6.9% of users went directly from viewing a doc to creating a chart, which is an in-app action that we want to help users complete (like how we hope you’ll successfully create the charts described in this guide!)

How to interpret?

This chart gives you insight into the percentage of users who are going back into your product after reading docs. Try tweaking this chart to be more specific in your steps to check for the success of your most popular docs based on what those docs are teaching users to do. For example, at Heap, we have a journey chart to check for installation success, where step 1 is a view of any installation guide, and step 2 is when a user installs Heap on the platform that the installation guide was for.

You can create new events for this, or filter broader events down by clicking the filter icon next to a step and entering your filter criteria. In this example, we’ll filter our View – Any docs page event down to only ones that contain the word ‘installation‘ in their URL to only see results for installation guides.

Chart 9: Heatmap of docs homepage

We recommend monitoring a heatmap of your docs site homepage to gauge the usefulness of your page sections. Steps to set this up: 

1. Navigate to Analyze > Heatmap
2. Add your docs site URL
3. Select date range – past 90 days (or whichever date range you’d like to see!)
4. Optional: Add filters to filter out internal users and bot traffic
5. Click View results to create this chart!

Your chart should be set up like this:

What does this tell you?

This will give you a visual representation of what users clicked on, mouse movement patterns, and how far they scrolled on your docs site. Use the Clicks, Scrolling, and Attention tabs on the side to go through your results.

How to interpret?

This information can help you make decisions about the layout of your homepage and other pages on your site. Here’s how to interpret each section:

• Clicks can give you insight into which sections and navigation elements are of the most interest to users. If an element that is most commonly clicked on is currently a smaller part of the page, you may want to make it bigger to improve the user experience.
• Scrolling can tell you if the placement of key elements is bringing value to your users. If you have a long homepage with several different sections, but most users aren’t scrolling far enough to see it, you may want to move things around to make those sections more discoverable, or remove them altogether. 
• Attention is similar to clicks, though it can help you understand where users might be reading or focusing their eyes on before clicking or leaving the page. If you notice a lot of attention on an item, but fewer clicks, you may want to revise the element (rewrite a nav item, or make it bigger and easier to click) to boost engagement.

To learn more about how to make the most of heatmaps, see Heatmap analysis overview.

Step 3: Interpret your results and take action

Set up a dashboard

Now that you’re measuring a wealth of valuable data, you’ll want to familiarize yourself with baselines and expected patterns of behavior so you can easily spot any unusual patterns. To make it easy to regularly check these charts, save them all to a dashboard so you’ll have all your docs metrics in one place!

At Heap, we check our docs insights dashboard once per month, so we have a good sense of the most popular docs, sections, search terms, and more. When we notice something unusual, like an uncommon search term that was used a lot in one month, we know to dig into that to better understand the change. We also regularly share this data with other teams to inform their decision making, including Product, Support, and Success, to compare to data that they’re seeing in their own charts.

Track percentages, not counts

In our experience, the best way to contextualize any metric is to go by percentages, not counts. For example, your marketing team might kick off a campaign where they email all new users with a link to the getting started guide 48 hours after signup. To track whether that campaign actually boosted views of that guide, you might set up a chart to measure a count of views of your getting started guide from before and after the time that marketing started sending those emails. 

When the results come in, your chart shows that 1000+ users viewed your getting started guide in the week after the emails started being sent, which sounds great! However, when you update your chart to compare a segment of users who actually received the email versus. users who didn’t, your discover only 2% of those views came from users who received that email.

For this reason, we recommend always comparing groups of users as part of your ongoing analysis, or using ratios to measure event A over event B.

Identify your audience and reach out

If you have Heap set up to track user identity, we recommend grouping by identity for all of these charts to see a breakdown of results by user. You may find you have “docs power users” you can reach out to for qualitative feedback. If you have account health analysis set up, you can also group by account to see which of your users use your docs the most, and tap into them as your “docs champions”.

We all know direct user feedback is the very best way to figure out how to make docs better, so use the data available to you to start those conversations with users! At Heap, we sometimes follow up on user feedback via email if they provided an email address when sharing docs feedback.

That said, if you’re still reading, we’re grateful that you took the time to check out our guide on “docs metrics for docs folks”. If you have any questions, feedback, or memes (we love docs-related humor) please feel free to reach out to us at docs@heap.io.