feedback.md

title	date	weight	description
Analytics, User Feedback, and SEO	2019-06-05	8	Add Google Analytics tracking to your site, and enable the page-feedback widget. See what data is used to create the meta description tag for SEO.

Adding Analytics

The Docsy theme builds upon Hugo's support for Google Analytics, which Hugo provides through internal templates. Once you set up analytics as described below, usage information for your site (such as page views) is sent to your Google Analytics account.

Prerequisites

You will need an analytics ID for your website before proceeding (technically it's called a measurement ID or property ID but we'll use the term "analytics ID" in this guide). If you don't have one, see the How to get started section of Introducing Google Analytics 4 (GA4).

{{% alert title="Tip" %}}

Your project's analytics ID is a string that starts with G- (a GA4 measurement ID) or UA- (a universal analytics property ID).

{{% /alert %}}

Setup

Enable Google Analytics by adding your project's analytics ID to the site configuration file. For details, see Configure Google Analytics.

{{% alert title="Warning" color="warning" %}}

You can configure your project's analytics ID by setting either the top-level googleAnalytics config parameter or services.googleAnalytics.id. Do not define both otherwise this will likely result in unexpected behavior. For details, see Is services.googleAnalytics.id an alias for googleAnalytics.

{{% /alert %}}

{{% alert title="Production-only feature!" color="primary" %}}

Analytics are enabled only for production builds (called "environments" in Hugo terminology). For the information Hugo environments and how to set them, see the following discussion.

{{% /alert %}}

User Feedback

By default Docsy puts a "was this page helpful?" feedback widget at the bottom of every documentation page, as shown in Figure 1.

Figure 1. The feedback widget, outlined in red

After clicking Yes the user should see a response like Figure 2. You can configure the response text in config.toml.

Figure 2. An example Yes response

How is this data useful?

When you have a lot of documentation, and not enough time to update it all, you can use the "was this page helpful?" feedback data to help you decide which pages to prioritize. In general, start with the pages with a lot of pageviews and low ratings. "Low ratings" in this context means the pages where users are clicking No --- the page wasn't helpful --- more often than Yes --- the page was helpful. You can also study your highly-rated pages to develop hypotheses around why your users find them helpful.

In general, you can develop more certainty around what patterns your users find helpful or unhelpful if you introduce isolated changes in your documentation whenever possible. For example, suppose that you find a tutorial that no longer matches the product. You update the instructions, check back in a month, and the score has improved. You now have a correlation between up-to-date instructions and higher ratings. Or, suppose you study your highly-rated pages and discover that they all start with code samples. You find 10 other pages with their code samples at the bottom, move the samples to the top, and discover that each page's score has improved. Since this was the only change you introduced on each page, it's more reasonable to believe that your users find code samples at the top of pages helpful. The scientific method, applied to technical writing, in other words!

Setup

1. Open config.toml/config.yaml/config.json.

2. Ensure that Google Analytics is enabled, as described above.

3. Set the response text that users see after clicking Yes or No.

   {{< tabpane persistLang=false >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="config.toml" lang="toml" >}} [params.ui.feedback] enable = true yes = 'Glad to hear it! Please tell us how we can improve.' no = 'Sorry to hear that. Please tell us how we can improve.' {{< /tab >}} {{< tab header="config.yaml" lang="yaml" >}} params: ui: feedback: enable: true 'yes': >- Glad to hear it! Please tell us how we can improve. 'no': >- Sorry to hear that. Please tell us how we can improve. {{< /tab >}} {{< tab header="config.json" lang="json" >}} { "params": { "ui": { "feedback": { "enable": true, "yes": "Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new\"> tell us how we can improve.", "no": "Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new\"> tell us how we can improve." } } } } {{< /tab >}} {{< /tabpane >}}

4. Save and close config.toml/config.yaml/config.json.

Access the feedback data

This section assumes basic familiarity with Google Analytics. For example, you should know how to check pageviews over a certain time range and navigate between accounts if you have access to multiple documentation sites.

1. Open Google Analytics.
2. Open Behavior > Events > Overview.
3. In the Event Category table click the Helpful row. Click view full report if you don't see the Helpful row.
4. Click Event Label. You now have a page-by-page breakdown of ratings.

Here's what the 4 columns represent:

• Total Events is the total number of times that users clicked either Yes or No.
• Unique Events provides a rough indication of how frequently users are rating your pages per session. For example, suppose your Total Events is 5000, and Unique Events is 2500. This means that you have 2500 users who are rating 2 pages per session.
• Event Value isn't that useful.
• Avg. Value is the aggregated rating for that page. The value is always between 0 and 1. When users click No a value of 0 is sent to Google Analytics. When users click Yes a value of 1 is sent. You can think of it as a percentage. If a page has an Avg. Value of 0.67, it means that 67% of users clicked Yes and 33% clicked No.

The underlying Google Analytics infrastructure that stores the "was this page helpful?" data is called Events. See docsy pull request #1 to see exactly what happens when a user clicks Yes or No. It's just a click event listener that fires the Google Analytics JavaScript function for logging an Event, disables the Yes and No buttons, and shows the response text.

Disable feedback on a single page

Add the parameter hide_feedback to the page's front matter and set it to true.

{{< tabpane persistLang=false >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} +++ hide_feedback = true +++ {{< /tab >}} {{< tab header="yaml" lang="yaml" >}}

hide_feedback: true

{{< /tab >}} {{< tab header="json" lang="json" >}} { "hide_feedback": true } {{< /tab >}} {{< /tabpane >}}

Disable feedback on all pages

Set params.ui.feedback.enable to false in config.toml/config.yaml/config.json:

{{< tabpane persistLang=false >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="config.toml" lang="toml" >}} [params.ui.feedback] enable = false {{< /tab >}} {{< tab header="config.yaml" lang="yaml" >}} params: ui: feedback: enable: false {{< /tab >}} {{< tab header="config.json" lang="json" >}} { "params": { "ui": { "feedback": { "enable": false } } } } {{< /tab >}} {{< /tabpane >}}

Add a contact form with Fabform

You can create a contact form for your site and collect your form submissions at fabform.io. To use this feature, you first need to sign up for an account with Fabform. The following example shows how to add a simple form that collects the user's email address to your site source:

<form action="https://fabform.io/f/{form-id}" method="post">
 <label for="email">Your Email</label>
 <input name="email" type="email">
 <button type="submit">Submit</button>
</form>

For more details, see Add a Hugo contact form in the Fabform documentation.

Search Engine Optimization meta tags

Check out Google's Search Engine Optimization (SEO) Starter Guide for how to optimize your site for SEO.

Google recommends using the description meta tag to tell search engines what your page is about. The Docsy theme creates and populates this meta tag for you in the layouts/partials/head.html file:

{{ if .Page.Description }}
  <meta name="description" content="{{ .Page.Description }}">
{{ else }}
  {{ $desc := (.Page.Content | safeHTML | truncate 150) }}
  <meta name="description" content="{{ $desc }}">
{{ end }}

.Page.Description is the text from the description [frontmatter field]({{< ref "content#page-frontmatter" >}}). If the page's frontmatter does not have a description, the first 150 characters of the page content is used instead.

For example, if your front matter description is:

{{< tabpane persistLang=false >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} +++ description = ''' Add Google Analytics tracking to your site. ''' +++ {{< /tab >}} {{< tab header="yaml" lang="yaml" >}}

description: > Add Google Analytics tracking to your site.

{{< /tab >}} {{< tab header="json" lang="json" >}} { "description": "Add Google Analytics tracking to your site.\n" } {{< /tab >}} {{< /tabpane >}}

Then the meta description tag on the rendered page is:

<meta name="description" content="Add Google Analytics tracking to your site.">

You can add additional meta tags to your own copy of the head-end.html partial. See [Customizing templates]({{< ref "lookandfeel#customizing-templates" >}}) for more information.