New Read the Docs tutorial, part III (and finale?)

docs/analytics.rst

@@ -27,6 +27,13 @@ You can enable it by:
 * Going to :guilabel:`Admin` > :guilabel:`Advanced Settings` in your project.
 * Fill in the **Analytics code** heading with your Google Tracking ID (example `UA-123456674-1`)
 
+.. figure:: /_static/images/google-analytics-options.png
+   :width: 80%
+   :align: center
+   :alt: Options to manage Google Analytics
+
+   Options to manage Google Analytics
+
 Once your documentation rebuilds it will include your Analytics tracking code and start sending data.
 Google Analytics usually takes 60 minutes,
 and sometimes can take up to a day before it starts reporting data.

docs/conf.py

@@ -61,6 +61,7 @@ def get_version():
     'poliastro': ('https://docs.poliastro.space/en/v0.15.2/', None),
     'qiskit': ('https://qiskit.org/documentation/', None),
     'myst-parser': ('https://myst-parser.readthedocs.io/en/v0.15.1/', None),
+    'writethedocs': ('https://www.writethedocs.org/', None),
 }
 hoverxref_intersphinx = [
    "sphinx",

docs/tutorial/index.rst

@@ -559,7 +559,125 @@ encouraging you to browse the latest version instead. Neat!
 
    Warning for old versions
 
-----
+Getting insights from your projects
+-----------------------------------
 
-That's the end of the tutorial,
-but you can learn more about the platform starting with our :doc:`/features` page.
+Once your project is up and running, you will probably want to understand
+how readers are using your documentation, addressing some common questions like:
+
+- what pages are the most visited pages?
+- what search terms are the most frequently used?
+- are readers finding what they look for?
+
+Read the Docs offers you some analytics tools to find out the answers.
+
+Traffic Analytics
+~~~~~~~~~~~~~~~~~
+
+The Traffic Analytics view shows the top viewed documentation pages of the past 30 days,
+plus a visualization of the daily views during that period.
+To generate some artificial views on your newly created project,
+you can first click around the different pages of your project,
+which will be accounted immediately for the current day statistics.
+
+To see the Traffic Analytics view, go back the :term:`project page` again,
+click on the "⚙ Admin" button, and then click on the "Traffic Analytics" section.
+You will see the list of pages in descending order of visits,
+as well as a plot similar to the one below.
+
+.. figure:: /_static/images/tutorial/traffic-analytics-plot.png
+   :width: 80%
+   :align: center
+   :alt: Traffic Analytics plot
+
+   Traffic Analytics plot
+
+.. note::
+
+   The Traffic Analytics view explained above gives you a simple overview
+   of how your readers browse your documentation. It has the advantage that
+   it stores very little information about your visitors,
+   and therefore it respects their privacy.
+   However, you might want to get more detailed data by
+   :ref:`enabling Google Analytics <analytics:Enabling Google Analytics on your Project>`.
+   Notice though that we take some extra measures to :ref:`respect user
+   privacy <advertising/advertising-details:analytics>`
+   when they visit projects that have Google Analytics enabled,
+   and this might reduce the number of visitors.
+
+Finally, you can also download this data for closer inspection.
+To do that, scroll to the bottom of the page
+and click on the :guilabel:`Download all data` button.
+That will prompt you to download a :abbr:`CSV (Comma-Separated Values)` file
+that you can process any way you want.
+
+.. note::
+
+   The amount of analytics data stored for download depends on the plan.
+   On the Community site, the last 90 days are stored.
+   On the Commercial one, it goes from 30 to infinity
+   (check out `the pricing page <https://readthedocs.com/pricing/>`_).
+
+Search Analytics
+~~~~~~~~~~~~~~~~
+
+Apart from traffic analytics, Read the Docs also offers the possibility
+to inspect what search terms your readers use on your documentation.
+This can inform decisions on what areas to reinforce,
+or what parts of your project are less understood or more difficult to find.
+
+To generate some artificial search statistics on the project,
+go to the HTML documentation, locate the Sphinx search box on the left,
+type ``ingredients``, and press the :kbd:`Enter` key.
+You will be redirected to the search results page, which will show two entries.
+
+Next, go back to the "⚙ Admin" section of your project page,
+and then click on the "Search Analytics" section.
+You will see a table with the most searched queries
+(including the ``ingredients`` one you just typed),
+how many results did each query return, and how many times it was searched.
+Below the queries table, you will also see a visualization
+of the daily number of search queries during the past 30 days.
+
+.. figure:: /_static/images/tutorial/search-analytics-terms.png
+   :width: 80%
+   :align: center
+   :alt: Most searched terms
+
+   Most searched terms
+
+Like the Traffic Analytics, you can also download the whole dataset in CSV format
+by clicking on the :guilabel:`Download all data` button.
+
+Where to go from here
+---------------------
+
+This is the end of the tutorial. You started by forking a GitHub repository
+and importing it on Read the Docs, building its HTML documentation,
+and then went through a series of steps to customize the build process,
+tweak the project configuration, and add new versions.
+
+Here you have some resources to continue learning about documentation
+and Read the Docs:
+
+- You can learn more about the functionality of the platform
+  by going over our :doc:`/features` page.
+- To make the most of the documentation generators that are supported,
+  you can read the :doc:`Sphinx tutorial <sphinx:tutorial/index>`
+  or the `MkDocs User Guide <https://www.mkdocs.org/user-guide/>`_.
+- Whether you are a documentation author, a project administrator, a developer, or a designer,
+  you can follow our how-to guides that cover specific tasks,
+  available under :doc:`/guides/index`.
+- You can check out some of the
+  :ref:`index:Advanced features of Read the Docs`,
+  like :doc:`/subprojects` or :doc:`/automation-rules`, to name a few.
+- For private project support and other enterprise features,
+  you can use :doc:`our commercial service </commercial/index>`
+  (and if in doubt, check out :doc:`/choosing-a-site`).
+- Do you want to join a global community of fellow `documentarians <writethedocs:documentarians>`?
+  Check out `Write the Docs <https://www.writethedocs.org/>`_ and
+  :doc:`its Slack workspace <writethedocs:slack>`.
+- Do you want to :doc:`contribute to Read the Docs </contribute>`?
+  We greatly appreciate it! Check out :doc:`/development/docs`.
+
+Happy documenting!