Docs: Split Traffic Analytics to a How-to guide and a Feature entry (Diátaxis)

docs/user/analytics.rst

@@ -1,4 +1,4 @@
-How To Use 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.

docs/user/guides/administrators.rst

@@ -16,7 +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>
+   Use traffic analytics </analytics>
    manage-translations-sphinx
    hiding-a-version
    deprecating-content

docs/user/guides/developers.rst

@@ -18,4 +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>
+   Use traffic analytics </analytics>

docs/user/guides/search-analytics.rst

@@ -1,6 +1,39 @@
-How To Use Search Analytics
+How to use search analytics
 ===========================
 
 In this guide, you can learn to use Read the Docs' built-in search analytics for your documentation project.
 
-TBC
+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 registered is displayed in the 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.
+
+* 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.
+
+* Try to repeat the search yourself and view the results list to inspect if the results are relevant.
+
+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.

docs/user/index.rst

@@ -185,6 +185,7 @@ and how to write successful documentation.
   :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>`
 
 * **For developers and designers**:
@@ -193,8 +194,8 @@ and how to write successful documentation.
   :doc:`/guides/reproducible-builds` |
   :doc:`/guides/embedding-content` |
   :doc:`/guides/conda` |
-  Setup Build Notifications <build-notifications> |
   :doc:`Use Traffic Analytics </analytics>` |
+  :doc:`/guides/build-notifications` |
   :doc:`More guides for developers and designers </guides/developers>`
 
 

docs/user/reference/analytics.rst

@@ -1,4 +1,4 @@
-Analytics for Search and Traffic
+Analytics for search and traffic
 ================================
 
 Read the Docs supports analytics for search and traffic.
@@ -7,10 +7,12 @@ we collect data about the vist and the referer
 with full respect of the privacy of the visitor.
 
 
-Traffic Analytics
+Traffic analytics
 -----------------
 
-Read the Docs aggregates simple statistics about visits to your documentation.
+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,
@@ -25,7 +27,7 @@ Learn more in :doc:`/analytics`.
 Search Analytics
 ----------------
 
-When someone visits your documentation using a search engine,
+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

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