diff --git a/userguide/content/en/docs/adding-content/feedback.md b/userguide/content/en/docs/adding-content/feedback.md index 4b0deec25f..55448acc38 100644 --- a/userguide/content/en/docs/adding-content/feedback.md +++ b/userguide/content/en/docs/adding-content/feedback.md @@ -1,34 +1,50 @@ --- -title: "Analytics, User Feedback, SEO" +title: Analytics, User Feedback, SEO date: 2019-06-05 +description: >- + Add Google Analytics tracking to your site, use the "was this page helpful?" + widget data, disable the widget on a single page or all pages, and change the + response text. See what data is used to create the `meta description` tag for + SEO. weight: 8 -description: > - Add Google Analytics tracking to your site, use the "was this page helpful?" widget data, disable the widget on a single - page or all pages, and change the response text. See what data is used to create the `meta description` tag for SEO. --- ## Adding Analytics -The Docsy theme contains built-in support for [Google Analytics](https://analytics.google.com/analytics/web/) via Hugo's [internal template](https://gohugo.io/templates/internal/#google-analytics), which is included in the theme. Once you set Analytics up as described below, usage information for your site (such as page views) is sent to your Google Analytics account. +The Docsy theme contains built-in support for +[Google Analytics](https://analytics.google.com/analytics/web/) via Hugo's +[internal template](https://gohugo.io/templates/internal/#google-analytics), +which is included in the theme. Once you set Analytics up as described below, +usage information for your site (such as page views) is sent to your Google +Analytics account. ### Setup -1. Ensure you have [set up a Google Analytics property](https://support.google.com/analytics/answer/1042508) for your site: this gives you an Analytics ID to add to your config, which Docsy in turn adds to all your site's pages. -1. Open `config.toml`/`config.yaml`/`config.json`. -1. Enable Google Analytics by setting the Tracking ID property to your site's Analytics ID. +1. Ensure you have + [set up a Google Analytics property](https://support.google.com/analytics/answer/1042508) + for your site: this gives you an Analytics ID to add to your config, which + Docsy in turn adds to all your site's pages. +2. Open `config.toml`/`config.yaml`/`config.json`. +3. Enable Google Analytics by setting the Tracking ID property to your site's + Analytics ID. {{< tabpane persistLang=false >}} + {{< tab header="Configuration file:" disabled=true />}} + {{< tab header="config.toml" lang="toml" >}} + [services.googleAnalytics] id = "UA-00000000-0" -{{< /tab >}} -{{< tab header="config.yaml" lang="yaml" >}} + +{{< /tab >}} {{< tab header="config.yaml" lang="yaml" >}} + services: googleAnalytics: id: UA-00000000-0 -{{< /tab >}} -{{< tab header="config.json" lang="json" >}} + +{{< /tab >}} {{< tab header="config.json" lang="json" >}} + { "services": { "googleAnalytics": { @@ -36,23 +52,27 @@ services: } } } + {{< /tab >}} - {{< /tabpane >}} +{{< /tabpane >}} -1. Save and close `config.toml`/`config.yaml`/`config.json`. -1. Ensure that your site is built with `HUGO_ENV="production"`, as Docsy only adds Analytics tracking to production-ready sites. You can specify this variable as a command line flag to Hugo: +4. Save and close `config.toml`/`config.yaml`/`config.json`. +5. Ensure that your site is built with `HUGO_ENV="production"`, as Docsy only + adds Analytics tracking to production-ready sites. You can specify this + variable as a command line flag to Hugo: - ``` + ```console $ env HUGO_ENV="production" hugo ``` - Alternatively, if you're using Netlify, you can specify it as a Netlify [deployment setting](https://www.netlify.com/docs/continuous-deployment/#build-environment-variables) in `netlify.toml` or the Netlify UI, along with the Hugo version. - + Alternatively, if you're using Netlify, you can specify it as a Netlify + [deployment setting](https://www.netlify.com/docs/continuous-deployment/#build-environment-variables) + in `netlify.toml` or the Netlify UI, along with the Hugo version. ## 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. +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`. +After clicking **Yes** the user should see a response like Figure 2. You can +configure the response text in `config.toml`.
- ### 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! +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`. -1. Ensure that Google Analytics is enabled, as described [above](#setup). -1. Set the response text that users see after clicking **Yes** or **No**. +1. Open `config.toml`/`config.yaml`/`config.json`. +2. Ensure that Google Analytics is enabled, as described [above](#setup). +3. Set the response text that users see after clicking **Yes** or **No**. {{< tabpane persistLang=false >}} -{{< tab header="Configuration file:" disabled=true />}} + {{< tab header="Configuration file:" disabled=true />}} + {{< tab header="config.toml" lang="toml" >}} [params.ui.feedback] enable = true @@ -121,8 +144,9 @@ params: 'no': >- Sorry to hear that. Please tell us how we can improve. -{{< /tab >}} -{{< tab header="config.json" lang="json" >}} + +{{< /tab >}}{{< tab header="config.json" lang="json" >}} + { "params": { "ui": { @@ -134,47 +158,54 @@ params: } } } + {{< /tab >}} - {{< /tabpane >}} +{{< /tabpane >}} -1. Save and close `config.toml`/`config.yaml`/`config.json`. +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. +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. -1. Open **Behavior** > **Events** > **Overview**. -1. In the **Event Category** table click the **Helpful** row. Click **view full report** if - you don't see the **Helpful** row. -1. Click **Event Label**. You now have a page-by-page breakdown of ratings. +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**. - -[events]: https://developers.google.com/analytics/devguides/collection/analyticsjs/events -[PR]: https://github.com/google/docsy/pull/1/files - -The underlying Google Analytics infrastructure that stores the "was this page helpful?" data is -called [Events][events]. See [docsy pull request #1][PR] 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. +- **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**. + +[events]: + https://developers.google.com/analytics/devguides/collection/analyticsjs/events +[pr]: https://github.com/google/docsy/pull/1/files + +The underlying Google Analytics infrastructure that stores the "was this page +helpful?" data is called [Events][events]. See [docsy pull request #1][pr] 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`. +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 />}} @@ -197,7 +228,8 @@ hide_feedback: true ### Disable feedback on all pages -Set `params.ui.feedback.enable` to `false` in `config.toml`/`config.yaml`/`config.json`: +Set `params.ui.feedback.enable` to `false` in +`config.toml`/`config.yaml`/`config.json`: {{< tabpane persistLang=false >}} {{< tab header="Configuration file:" disabled=true />}} @@ -224,27 +256,36 @@ params: {{< /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](https://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: +You can create a contact form for your site and collect your form submissions at +[fabform.io](https://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: ```html
- +
``` -For more details, see [Add a Hugo contact form](https://fabform.io/a/hugo-contact-form) in the Fabform documentation. - +For more details, see +[Add a Hugo contact form](https://fabform.io/a/hugo-contact-form) in the Fabform +documentation. ## Search Engine Optimization meta tags -Check out Google's [Search Engine Optimization (SEO) Starter Guide](https://developers.google.com/search/docs/beginner/seo-starter-guide) for how to optimize your site for SEO. +Check out Google's +[Search Engine Optimization (SEO) Starter Guide](https://developers.google.com/search/docs/beginner/seo-starter-guide) +for how to optimize your site for SEO. -Google [recommends](https://developers.google.com/search/docs/beginner/seo-starter-guide?hl=en%2F#descriptionmeta) 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: +Google +[recommends](https://developers.google.com/search/docs/beginner/seo-starter-guide?hl=en%2F#descriptionmeta) +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: ```html {{ if .Page.Description }} @@ -255,7 +296,10 @@ Google [recommends](https://developers.google.com/search/docs/beginner/seo-start {{ 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. +`.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: @@ -287,5 +331,7 @@ Then the meta `description` tag on the rendered page is: ``` -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. - +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.