2 files changed, 92 insertions, 0 deletions
diff --git a/browser/components/search/docs/index.rst b/browser/components/search/docs/index.rst
new file mode 100644
index 0000000000..42625189db
--- /dev/null
+++ b/browser/components/search/docs/index.rst
@@ -0,0 +1,21 @@
+Search
+======
+
+This document describes the implementation of parts of Firefox's search interfaces.
+
+The search area covers:
+
+  * Search bar on the toolbar
+  * In-content search
+  * One-off search buttons on both the search and address bars
+
+Search Engine handling is taken care of with the `toolkit Search Service`_.
+
+Most of the search code lives in `browser/components/search`_.
+
+.. toctree::
+
+   telemetry
+
+.. _toolkit Search Service: /toolkit/search/index.html
+.. _browser/components/search: https://searchfox.org/mozilla-central/source/browser/components/search
diff --git a/browser/components/search/docs/telemetry.rst b/browser/components/search/docs/telemetry.rst
new file mode 100644
index 0000000000..90737e31cf
--- /dev/null
+++ b/browser/components/search/docs/telemetry.rst
@@ -0,0 +1,71 @@
+Telemetry
+=========
+
+This section describes existing telemetry probes measuring interaction with
+search engines.
+
+Note: Some search related probes are also documented on the `address bar telemetry`_
+page.
+
+.. toctree::
+   :caption: Table of Contents
+
+   telemetry
+
+Search probes relevant to front-end searches
+--------------------------------------------
+
+The following probes are all handled by `SearchSERPTelemetry.jsm and the associated parent/child actors`_.
+
+Definitions:
+
+  * ``organic`` is a search that a user performs by visiting a search engine
+    directly.
+  * ``SAP`` (search access point) is a search that a user performs by visiting
+    via one of Firefox's access points, using the associated partner codes.
+  * ``sap-follow-on`` is a SAP search where the user has first accessed the site
+    via a SAP, and then performed an additional search.
+  * ``tagged`` refers to a page that is tagged with an associated partner code.
+    It may or may not have originated via an SAP.
+  * ``SERP`` refers to a search engine result page.
+
+SEARCH_COUNTS
+  This histogram records search counts for visits to SERP in-content pages. It
+  also stores other items - see `address bar telemetry`_. For in-content
+  searches, the format is
+  ``<provider>.in-content:[sap|sap-follow-on|organic]:[code|none]``.
+
+browser.search.withads.*
+  These keyed scalar track counts of SERP pages with adverts displayed. The key
+  format is ``<provider>:<tagged|organic>``.
+
+  They are broken down by the originating SAP where known:
+
+  - ``urlbar``  Except search mode.
+  - ``urlbar_searchmode``  Used when the Urlbar is in search mode.
+  - ``searchbar``
+  - ``about_home``
+  - ``about_newtab``
+  - ``contextmenu``
+  - ``webextension``
+  - ``system`` Indicates a search from the command line.
+  - ``unknown`` Indicates the origin was unknown.
+
+browser.search.adclicks.*
+  This is the same as ```browser.search.withads.*`` but tracks counts for them
+  clicks of adverts on SERP pages.
+
+browser.search.with_ads
+  Obsolete. This is being replaced by ``browser.search.withads.*``.
+
+  This keyed scalar records counts of SERP pages with adverts displayed.
+  The key format is ``<provider>:<sap|organic>``.
+
+browser.search.ad_clicks
+  Obsolete. This is being replaced by ``browser.search.adclicks.*``.
+
+  Records clicks of adverts on SERP pages. The key format is
+  ``<provider>:<sap|organic>``.
+
+.. _address bar telemetry: /browser/urlbar/telemetry.html
+.. _SearchSERPTelemetry.jsm and the associated parent/child actors: https://searchfox.org/mozilla-central/search?q=&path=SearchSERPTelemetry*.jsm&case=false&regexp=false