new file mode 100644
--- /dev/null
+++ b/browser/docs/UITelemetry.rst
@@ -0,0 +1,107 @@
+=======================
+UITelemetry data format
+=======================
+
+UI Telemetry sends its data as a JSON blob. This document describes the different parts
+of the JSON blob.
+
+``toolbars``
+------------
+
+This tracks the state of the user's UI customizations. It has the following properties:
+
+- ``sizemode`` - string indicating whether the window is in maximized, normal (restored) or
+  fullscreen mode;
+- ``bookmarksBarEnabled`` - boolean indicating whether the bookmarks bar is visible;
+- ``menuBarEnabled`` - boolean indicating whether the menu bar is visible (always false on OS X);
+- ``titleBarEnabled`` - boolean indicating whether the (real) titlebar is visible (rather than
+  having tabs in the titlebar);
+- ``defaultKept`` - list of strings identifying toolbar buttons and items that are still in their
+  default position. Only the IDs of builtin widgets are sent (ie not add-on widgets);
+- ``defaultMoved`` - list of strings identifying toolbar buttons and items that are no longer in
+  their default position, but have not been removed to the palette. Only the IDs of builtin widgets
+  are sent (ie not add-on widgets);
+- ``nondefaultAdded`` - list of strings identifying toolbar buttons and items that have been added
+  from the palette. Only the IDs of builtin widgets are sent (ie not add-on widgets);
+- ``defaultRemoved`` - list of strings identifying toolbar buttons and items that are in the
+  palette that are elsewhere by default. Only the IDs of builtin widgets are sent
+  (ie not add-on widgets);
+- ``addonToolbars`` - the number of non-default toolbars that are customizable. 1 by default
+  because it counts the add-on bar shim;
+- ``visibleTabs`` - array of the number of visible tabs per window;
+- ``hiddenTabs`` - array of the number of hidden tabs per window (ie tabs in panorama groups which
+  are not the current group);
+- ``countableEvents`` - please refer to the next section.
+- ``durations`` - an object mapping descriptions to duration records, which records the amount of
+  time a user spent doing something. Currently only has one property:
+   - ``customization`` - how long a user spent customizing the browser. This is an array of
+     objects, where each object has a ``duration`` property indicating the time in milliseconds,
+     and a ``bucket`` property indicating a bucket in which the duration info falls.
+
+``countableEvents``
+-------------------
+
+Countable events are stored under the ``toolbars`` section. They count the number of times certain
+events happen. No timing or other correlating information is stored - purely the number of times
+things happen.
+
+``countableEvents`` is an object with properties representing buckets. In each bucket, there is an
+object with the following properties:
+
+- ``click-builtin-item`` is an object tracking clicks on builtin customizable toolbar items, keyed
+  off the item IDs, with an object for each item with keys ``left``, ``middle`` and ``right`` each
+  storing a number indicating how often the respective type of click has happened.
+- ``click-menu-button`` is the same, except the item ID is always 'button'.
+- ``click-bookmarks-bar`` is the same, with the item IDs being replaced by either ``container`` for
+  clicks on bookmark or livemark folders, and ``item`` for individual bookmarks.
+- ``click-menubar`` is similar, with the item IDs being replaced by one of ``menu``, ``menuitem``
+  or ``other``, depending on the kind of item clicked. Note that this is not tracked on OS X, where
+  we can't listen for these events because of the global menubar.
+- ``click-bookmarks-menu-button`` is also similar, with the item IDs being replaced by:
+   - ``menu`` for clicks on the 'menu' part of the item;
+   - ``add`` for clicks that add a bookmark;
+   - ``edit`` for clicks that open the panel to edit an existing bookmark;
+   - ``in-panel`` for clicks when the button is in the menu panel, and clicking it does none of the
+     above;
+- ``customize`` tracks different types of customization events without the ``left``, ``middle`` and
+  ``right`` distinctions. The different events are the following, with each storing a count of the
+  number of times they occurred:
+   - ``start`` counts the number of times the user starts customizing;
+   - ``add`` counts the number of times an item is added somewhere from the palette;
+   - ``move`` counts the number of times an item is moved somewhere else (but not to the palette);
+   - ``remove`` counts the number of times an item is removed to the palette;
+   - ``reset`` counts the number of times the 'restore defaults' button is used;
+
+
+``UITour``
+----------
+The UI Tour has its own section in the UI Telemetry output, outside of the ``toolbars`` section.
+It has a single property ``seenPageIDs`` which tracks which UI Tour pages have been run.
+
+``contextmenu``
+---------------
+We track context menu interactions to figure out which ones are most often used and/or how
+effective they are. In the ``contextmenu`` object, we first store things per-bucket. Next, we
+divide the following different context menu situations:
+
+- ``selection`` if there is content on the page that's selected on which the user clicks;
+- ``link`` if the user opened the context menu for a link
+- ``image-link`` if the user opened the context menu on an image or canvas that's a link;
+- ``image`` if the user opened the context menu on an image (that isn't a link);
+- ``canvas`` if the user opened the context menu on a canvas (that isn't a link);
+- ``media`` if the user opened the context menu on an HTML video or audio element;
+- ``input`` if the user opened the context menu on a text input element;
+- ``social`` if the user opened the context menu inside a social frame;
+- ``other`` for all other openings of the content menu;
+
+Each of these objects (if they exist) then gets a "withcustom" and/or a "withoutcustom" property
+for context menus opened with custom page-created items and without them, and each of those
+properties holds an object with IDs corresponding to a count of how often an item with that ID was
+activated in the context menu. Only builtin context menu items are tracked, and besides those items
+there are four special items which get counts:
+
+- ``close-without-interaction`` is incremented when the user closes the context menu without interacting with it;
+- ``custom-page-item`` is incremented when the user clicks an item that was created by the page;
+- ``unknown`` is incremented when an item without an ID was clicked;
+- ``other-item`` is incremented when an add-on-provided menuitem is clicked.
+

new file mode 100644
--- /dev/null
+++ b/browser/docs/index.rst
@@ -0,0 +1,9 @@
+=======
+Firefox
+=======
+
+This is the nascent documentation of the Firefox front-end code.
+
+.. toctree::
+   :maxdepth: 1
+

--- a/browser/moz.build
+++ b/browser/moz.build
@@ -1,16 +1,18 @@
 # -*- Mode: python; c-basic-offset: 4; indent-tabs-mode: nil; tab-width: 40 -*-
 # vim: set filetype=python:
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 CONFIGURE_SUBST_FILES += ['installer/Makefile']
 
+SPHINX_TREES['browser'] = 'docs'
+
 DIRS += [
     'base',
     'components',
     'experiments',
     'fuel',
     'locales',
     'modules',
     'themes',