diff --git a/docs/user/_static/images/search-analytics-demo.png b/docs/user/_static/images/search-analytics-demo.png index 048849460b0..872d7eca025 100644 Binary files a/docs/user/_static/images/search-analytics-demo.png and b/docs/user/_static/images/search-analytics-demo.png differ diff --git a/docs/user/analytics.rst b/docs/user/analytics.rst index bc20b83962e..95dfafa6bc1 100644 --- 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 index 5c9c72bc1a2..a126867b390 100644 --- 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 Enable Canonical URLs technical-docs-seo-guide + Use traffic analytics manage-translations-sphinx hiding-a-version deprecating-content diff --git a/docs/user/guides/authors.rst b/docs/user/guides/authors.rst index bee3292d65d..cf5e9b0ce93 100644 --- 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 enable-offline-formats + Using search analytics diff --git a/docs/user/guides/developers.rst b/docs/user/guides/developers.rst index 05b91559ea6..8ec157046eb 100644 --- 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 + Use traffic analytics diff --git a/docs/user/guides/search-analytics.rst b/docs/user/guides/search-analytics.rst new file mode 100644 index 00000000000..4c3c8865743 --- /dev/null +++ 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 index aacc0a6896b..d9a33a4ad4b 100644 --- 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 ` | + :doc:`Use Traffic Analytics ` | :doc:`/guides/build-notifications` | :doc:`More guides for 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 ` | :doc:`/guides/build-notifications` | :doc:`More guides for developers and designers ` diff --git a/docs/user/reference/analytics.rst b/docs/user/reference/analytics.rst new file mode 100644 index 00000000000..5a582bce2c4 --- /dev/null +++ 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 ` 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 new file mode 100644 index 00000000000..31f9aeb327e --- /dev/null +++ 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 index cd19098e682..daff3022967 100644 --- 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