Update Analytics pages in the docs (#11636)

ericholscher · humitos · agjohnson · web-flow · commit 06ebe4040f94 · 2024-10-07T11:31:26.000-07:00
* Update Analytics pages in the docs This builds our properly feature pages for them, and remove the old reference page that combined both. Fixes #11587 * Fix links * Update docs/user/traffic-analytics.rst Co-authored-by: Manuel Kaufmann <humitos@gmail.com> * Apply suggestions from code review Co-authored-by: Anthony <aj@ohess.org> * Update language and seealso --------- Co-authored-by: Manuel Kaufmann <humitos@gmail.com> Co-authored-by: Anthony <aj@ohess.org>
diff --git a/docs/user/analytics.rst b/docs/user/analytics.rst
diff --git a/docs/user/guides/content/index.rst b/docs/user/guides/content/index.rst
@@ -34,7 +34,7 @@ How-to guides: content, themes and SEO
 ⏩️ :doc:`Enabling offline formats </guides/enable-offline-formats>`
     This guide provides step-by-step instructions to enabling offline formats of your documentation.
 
-⏩️ :doc:`Using search analytics </guides/search-analytics>`
+⏩️ :doc:`Using search analytics </search-analytics>`
     In this guide, you can learn to use Read the Docs' built-in search analytics for your documentation project.
 
 ⏩️ :doc:`Adding custom CSS or JavaScript to Sphinx documentation </guides/adding-custom-css>`
@@ -58,7 +58,7 @@ How-to guides: content, themes and SEO
 
    Search engine optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>
    Using traffic analytics </analytics>
-   Using search analytics </guides/search-analytics>
+   Using search analytics </search-analytics>
    Enabling offline formats </guides/enable-offline-formats>
    Embedding content from your documentation </guides/embedding-content>
    Managing translations for Sphinx projects </guides/manage-translations-sphinx>
diff --git a/docs/user/guides/setup/monorepo.rst b/docs/user/guides/setup/monorepo.rst
@@ -70,7 +70,7 @@ For each project, it's now possible to configure:
 * :doc:`Custom redirect rules </guides/custom-domains>`
 * :doc:`Custom domains </guides/custom-domains>`
 * :doc:`Automation rules </automation-rules>`
-* :doc:`Traffic and search analytics </reference/analytics>`
+* :doc:`Traffic analytics </traffic-analytics>`
 * Additional documentation tools with individual :doc:`build processes </build-customization>`:
   One project might use :doc:`Sphinx <sphinx:index>`,
   while another project setup might use `Asciidoctor <https://asciidoctor.org/>`__.
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -70,7 +70,8 @@ Read the Docs: documentation simplified
    :caption: Maintaining projects
 
    /user-defined-redirects
-   /reference/analytics
+   /traffic-analytics
+   /search-analytics
    /security-log
    /badges
    /explanation/documentation-structure
@@ -210,7 +211,7 @@ Keep your documentation up to date:
 :doc:`/user-defined-redirects`
   Redirect your old URLs to new ones.
 
-:doc:`/reference/analytics`
+:doc:`/traffic-analytics`
   Learn more about how users are interacting with your documentation.
 
 :doc:`/security-log`
diff --git a/docs/user/reference/analytics.rst b/docs/user/reference/analytics.rst
diff --git a/docs/user/reference/features.rst b/docs/user/reference/features.rst
@@ -31,10 +31,11 @@ Feature reference
 ⏩️ :doc:`/build-notifications`
   Build notifications can alert you when your builds fail so you can take immediate action.
 
-⏩️ :doc:`/reference/analytics`
-  Traffic and Search analytics are built into the platform.
-  This allows you to easily see what the most popular pages are,
-  and what people are searching for.
+⏩️ :doc:`/traffic-analytics`
+  Traffic analytics help you understand how your documentation is being used.
+
+⏩️ :doc:`/search-analytics`
+  Search analytics allow you to see what your users are searching for.
 
 ⏩️ :doc:`/user-defined-redirects`
   Projects may define their own custom URL redirects,
diff --git a/docs/user/search-analytics.rst b/docs/user/search-analytics.rst
@@ -1,7 +1,18 @@
-How to use search analytics
-===========================
+Search analytics
+================
 
-In this guide, you can learn to use Read the Docs' built-in search analytics for your documentation project.
+When someone visits your documentation and uses the built-in :doc:`server side search </server-side-search/index>` feature,
+Read the Docs will collect analytics on their search queries.
+
+These are aggregated into a simple view of the
+"Top queries in the past 30 days".
+You can also download this data.
+
+This is helpful to optimize your documentation in alignment with your readers' interests.
+You can discover new trends and expand your documentation to new needs.
+
+Using search analytics
+----------------------
 
 To see a list of the top queries and an overview from the last month,
 go to the :guilabel:`Admin` tab of your project,
@@ -39,3 +50,19 @@ The number of times the query has been used in a search is displayed as the **se
 In **Daily search totals**, you can see trends that might match special events in your project's publicity.
 If you wish to analyze these numbers in details, click :guilabel:`Download all data`
 to get a CSV formatted file with all available search analytics.
+
+Data storage
+------------
+
+The duration of analytics data stored depends on which site you're using:
+
+* On |org_brand|, the last 90 days are stored.
+* On |com_brand|, storage duration starts at 30 days and increases with plan level.
+
+.. seealso::
+
+   `Our plan pricing <https://about.readthedocs.com/pricing/>`_
+      Compare our plan pricing and analytics storage duration.
+
+   :doc:`/traffic-analytics`
+      See how users are using your documentation.
diff --git a/docs/user/server-side-search/index.rst b/docs/user/server-side-search/index.rst
@@ -62,7 +62,7 @@ API
 
 Analytics
    Know what your users are searching for.
-   See :doc:`/guides/search-analytics`
+   See :doc:`/search-analytics`
 
 .. _"full-text search": https://docs.readthedocs.io/en/latest/search.html?q=%22full-text+search%22
 .. _"project:docs project:dev search": https://docs.readthedocs.io/en/latest/search.html?q=project:docs+project:dev+search
@@ -72,7 +72,7 @@ Analytics
    :align: center
    :alt: Search analytics demo
 
-   Search analytics demo. Read more in :doc:`/guides/search-analytics`.
+   Search analytics demo. Read more in :doc:`/search-analytics`.
 
 .. _Elasticsearch: https://www.elastic.co/products/elasticsearch
 
diff --git a/docs/user/traffic-analytics.rst b/docs/user/traffic-analytics.rst
@@ -0,0 +1,45 @@
+Traffic analytics
+=================
+
+Read the Docs aggregates statistics about visits to your documentation.
+This is mainly information about how often pages are viewed,
+and which return a `404 Not Found` error code.
+
+Traffic analytics let you see *which* documents your users are reading.
+This allows you to understand how your documentation is being used,
+so you can focus on expanding and updating parts people are reading most.
+
+To see a list of the top pages from the last month,
+go to the :guilabel:`Admin` tab of your project,
+and then click on :guilabel:`Traffic analytics`.
+
+.. figure:: /_static/images/addons-analytics.png
+   :width: 50%
+   :align: center
+   :alt: Traffic analytics demo
+
+   Traffic analytics demo
+
+Enabling traffic analytics
+--------------------------
+
+#. Go to the new :term:`dashboard`:
+#. Click on a project name.
+#. Go to :guilabel:`Settings`, then in the left bar, go to :guilabel:`Addons`.
+#. Go to :guilabel:`Analytics` and check :guilabel:`Analytics enabled`.
+
+Data storage
+------------
+
+The duration of analytics data stored depends on which site you're using:
+
+* On |org_brand|, the last 90 days are stored.
+* On |com_brand|, storage duration starts at 30 days and increases with plan level.
+
+.. seealso::
+
+   `Our plan pricing <https://about.readthedocs.com/pricing/>`_
+      Compare our plan pricing and analytics storage duration.
+
+   :doc:`/search-analytics`
+      See what users are searching for in your documentation.
diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst
@@ -550,7 +550,7 @@ and click the :guilabel:`Download all data` button.
 Understanding search analytics
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-As well as traffic analytics, Read the Docs shows :doc:`what terms your readers are searching for </guides/search-analytics>`.
+As well as traffic analytics, Read the Docs shows :doc:`what terms your readers are searching for </search-analytics>`.
 This can inform decisions on what areas to focus on,
 or what parts of your project are less understood or more difficult to find.
 
