Merge branch 'diataxis/main' of github.com:readthedocs/readthedocs.org into diataxis/main

benjaoming · benjaoming · commit ed88ca7eeb7d · 2023-01-03T13:19:55.000+01:00
diff --git a/docs/user/_static/images/search-analytics-demo.png b/docs/user/_static/images/search-analytics-demo.png
diff --git a/docs/user/analytics.rst b/docs/user/analytics.rst
@@ -1,5 +1,8 @@
-Traffic Analytics
-=================
+How to use traffic analytics
+============================
+
+In this guide, you can learn to use Read the Docs' built-in traffic analytics for your documentation project.
+You will also learn how to optionally add your own Google Analytics account or completely disable Google Analytics on your project.
 
 Traffic Analytics lets you see *which* documents your users are reading.
 This allows you to understand how your documentation is being used,
diff --git a/docs/user/guides/administrators.rst b/docs/user/guides/administrators.rst
@@ -16,6 +16,7 @@ have a look at our :doc:`/tutorial/index`.
    Manage Custom Domains <custom-domains>
    Enable Canonical URLs <canonical-urls>
    technical-docs-seo-guide
+   Use traffic analytics </analytics>
    manage-translations-sphinx
    hiding-a-version
    deprecating-content
diff --git a/docs/user/guides/authors.rst b/docs/user/guides/authors.rst
@@ -18,3 +18,4 @@ and :doc:`/intro/getting-started-with-mkdocs`.
    jupyter
    Migrate from rST to MyST <migrate-rest-myst>
    enable-offline-formats
+   Using search analytics <search-analytics>
diff --git a/docs/user/guides/developers.rst b/docs/user/guides/developers.rst
@@ -18,3 +18,4 @@ or customize the documentation appearance.
    build-using-too-many-resources
    edit-source-links-sphinx
    Setup Build Notifications <build-notifications>
+   Use traffic analytics </analytics>
diff --git a/docs/user/guides/search-analytics.rst b/docs/user/guides/search-analytics.rst
@@ -0,0 +1,41 @@
+How to use search analytics
+===========================
+
+In this guide, you can learn to use Read the Docs' built-in search analytics for your documentation project.
+
+To see a list of the top queries and an overview from the last month,
+go to the :guilabel:`Admin` tab of your project,
+and then click on :guilabel:`Search Analytics`.
+
+.. figure:: /_static/images/search-analytics-demo.png
+   :width: 50%
+   :align: center
+   :alt: Search analytics demo
+
+   How the search analytics page looks.
+
+In **Top queries in the past 30 days**,
+you see all the latest searches ordered by their popularity.
+The list itself is often longer than what meets the eye,
+Scroll downwards on the list itself to see more results.
+
+Understanding your analytics
+----------------------------
+
+In **Top queries in the past 30 days**, you can see the most popular terms that users have searched for.
+Next to the search query, the number of actual **results** for that query is shown.
+The number of times the query has been used in a search is displayed as the **searches** number.
+
+* If you see a search term that doesn't have any results,
+  you could apply that term in documentation articles or create new ones.
+  This is a great way to understand missing gaps in your documentation.
+
+* If a search term is often used but the documentation article exists,
+  it can also indicate that it's hard to navigate to the article.
+
+* Repeat the search yourself and inspect the results to see if they are relevant.
+  You can add keywords to various pages that you want to show up for searches on that page.
+
+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.
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -105,6 +105,7 @@ to help you create fantastic documentation for your project.
    :glob:
 
    api/index
+   reference/features
 
 
 Read the Docs feature overview
@@ -151,7 +152,6 @@ and some of the core features of Read the Docs.
    /versions
    /hosting
    /server-side-search/index
-   /analytics
    /security-log
 
    /connected-accounts
@@ -186,6 +186,7 @@ and how to write successful documentation.
   :doc:`/guides/manage-translations-sphinx` |
   :doc:`/guides/private-submodules` |
   :doc:`Configure Pull Request Builds </guides/pull-requests>` |
+  :doc:`Use Traffic Analytics </analytics>` |
   :doc:`/guides/build-notifications` |
   :doc:`More guides for administrators </guides/administrators>`
 
@@ -195,6 +196,7 @@ and how to write successful documentation.
   :doc:`/guides/reproducible-builds` |
   :doc:`/guides/embedding-content` |
   :doc:`/guides/conda` |
+  :doc:`Use Traffic Analytics </analytics>` |
   :doc:`/guides/build-notifications` |
   :doc:`More guides for developers and designers </guides/developers>`
 
diff --git a/docs/user/reference/analytics.rst b/docs/user/reference/analytics.rst
@@ -0,0 +1,40 @@
+Analytics for search and traffic
+================================
+
+Read the Docs supports analytics for search and traffic.
+When someone reads your documentation,
+we collect data about the vist and the referer
+with full respect of the privacy of the visitor.
+
+
+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 lets 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.
+
+If you require more detailed analytics, Read the Docs has native support for Google Analytics.
+It's also possible to customize your documentation to include other analytics frameworks.
+
+Learn more in :doc:`/analytics`.
+
+
+Search Analytics
+----------------
+
+When someone visits your documentation and uses the built-in :ref:`server-side search <server-side-search:Server Side Search>` feature,
+Read the Docs will collect analytics on their search term.
+
+Those 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.
+
+Learn more in :doc:`/guides/search-analytics`.
diff --git a/docs/user/reference/features.rst b/docs/user/reference/features.rst
@@ -0,0 +1,9 @@
+========
+Features
+========
+
+
+.. toctree::
+   :maxdepth: 1
+
+   analytics
diff --git a/docs/user/server-side-search/index.rst b/docs/user/server-side-search/index.rst
@@ -65,23 +65,19 @@ API
    Integrate our search as you like.
    See :doc:`/server-side-search/api`.
 
+Analytics
+   Know what your users are searching for.
+   See :doc:`/guides/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
 
-Search analytics
-----------------
-
-Know what your users are looking for in your docs.
-To see a list of the top queries and an overview from the last month,
-go to the :guilabel:`Admin` tab of your project,
-and then click on :guilabel:`Search Analytics`.
-
 .. figure:: /_static/images/search-analytics-demo.png
    :width: 50%
    :align: center
    :alt: Search analytics demo
 
-   Search analytics demo
+   Search analytics demo. Read more in :doc:`/guides/search-analytics`.
 
 .. _Elasticsearch: https://www.elastic.co/products/elasticsearch
 
