Update Google Analytics section of UG (#1098)

2 files changed, 42 insertions, 50 deletions

diff --git a/userguide/config.toml b/userguide/config.toml
index 2bfe49c..c4421bc 100644
--- a/userguide/config.toml
+++ b/userguide/config.toml
@@ -44,8 +44,7 @@ anchor = "smart"
 
 [services]
 [services.googleAnalytics]
-# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback].
-id = "UA-00000000-0"
+id = "UA-00000000-0" # FIXME: https://github.com/google/docsy/issues/1097
 
 # Language configuration
 
@@ -131,10 +130,8 @@ sidebar_search_disable = false
 # Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar
 navbar_logo = true
 
-# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.
-# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
-# If you want this feature, but occasionally need to remove the "Feedback" section from a single page,
-# add "hide_feedback: true" to the page's front matter.
+# For details concerning the page feedback widget, see
+# https://www.docsy.dev/docs/adding-content/feedback/#user-feedback
 [params.ui.feedback]
 enable = true
 # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
diff --git a/userguide/content/en/docs/adding-content/feedback.md b/userguide/content/en/docs/adding-content/feedback.md
index 70350c4..55f0439 100644
--- a/userguide/content/en/docs/adding-content/feedback.md
+++ b/userguide/content/en/docs/adding-content/feedback.md
@@ -1,5 +1,5 @@
 ---
-title: Analytics, User Feedback, SEO
+title: Analytics, User Feedback, and SEO
 date: 2019-06-05
 description: >-
   Add Google Analytics tracking to your site, collect user feedback and learn
@@ -9,63 +9,53 @@ weight: 8
 
 ## 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 builds upon [Hugo's support for Google Analytics][hugo-ga],
+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.
 
-### Setup
+### Prerequisites
 
-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.
+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)][ga4-intro].
 
-    {{< tabpane persistLang=false >}}
+{{% alert title="Tip" %}}
 
-{{< tab header="Configuration file:" disabled=true />}}
+  Your project's **analytics ID** is a string that starts with `G-` (a GA4
+  measurement ID) or `UA-` (a universal analytics property ID).
 
-{{< tab header="config.toml" lang="toml" >}}
+{{% /alert %}}
 
-[services.googleAnalytics]
-id = "UA-00000000-0"
+### Setup
 
-{{< /tab >}} {{< tab header="config.yaml" lang="yaml" >}}
+Enable Google Analytics by adding your project's analytics ID to the site
+configuration file. For details, see [Configure Google Analytics][].
 
-services:
-  googleAnalytics:
-    id: UA-00000000-0
+{{% alert title="Warning" color="warning" %}}
+  <!-- Remove this warning once the Hugo docs have been updated to include it. -->
 
-{{< /tab >}} {{< tab header="config.json" lang="json" >}}
+  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 can result in [unexpected behavior][]. For
+  details, see [Is services.googleAnalytics.id an alias for
+  googleAnalytics][alias-discussion].
 
-{
-  "services": {
-    "googleAnalytics": {
-      "id": "UA-00000000-0"
-    }
-  }
-}
+  [alias-discussion]: https://discourse.gohugo.io/t/config-is-services-googleanalytics-id-an-alias-for-googleanalytics/39469
+  [unexpected behavior]: https://github.com/google/docsy/issues/921
 
-{{< /tab >}}
-{{< /tabpane >}}
+{{% /alert %}}
 
-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:
+{{% alert title="Production-only feature!" color="primary" %}}
+
+  Analytics are enabled _only_ for **production** builds (called "environments"
+  in Hugo terminology). For information about Hugo environments and how to set
+  them, see the following [discussion][].
 
-    ```console
-    $ env HUGO_ENV="production" hugo
-    ```
+  [discussion]: https://discourse.gohugo.io/t/what-does-setting-hugo-env-to-production-do/24669/2
 
-    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.
+{{% /alert %}}
 
 ## User Feedback
 
@@ -296,6 +286,11 @@ Add more meta tags as needed to your project's copy of the `head-end.html`
 partial. For details, see [Customizing templates]({{< ref "lookandfeel#customizing-templates"
 >}}).
 
+[Configure Google Analytics]: https://gohugo.io/templates/internal/#configure-google-analytics
+[ga4-intro]: https://support.google.com/analytics/answer/1042508
+[Google Analytics]: https://analytics.google.com/analytics/web/
+[hugo-ga]: https://gohugo.io/templates/internal/#google-analytics
+[internal templates]: https://gohugo.io/templates/internal/
 [layouts/partials/page-description.html]: https://github.com/google/docsy/blob/main/layouts/partials/page-description.html
 [site `params`]: https://gohugo.io/variables/site/#the-siteparams-variable
 [summary]: https://gohugo.io/content-management/summaries/