From 2d43b0bd64b08ff8da27c31af3e8aa97d8a8eaef Mon Sep 17 00:00:00 2001
From: Mark Finkle <mfinkle@mozilla.com>
Date: Fri, 18 Dec 2015 17:21:00 -0500
Subject: [PATCH] Bug 1232746 - Document process for generating inline
 autocomplete domain list r=margaret

---
 mobile/android/base/docs/index.rst     |  1 +
 mobile/android/docs/defaultdomains.rst | 68 ++++++++++++++++++++++++++
 mobile/android/docs/index.rst          |  1 +
 3 files changed, 70 insertions(+)
 create mode 100644 mobile/android/docs/defaultdomains.rst

diff --git a/mobile/android/base/docs/index.rst b/mobile/android/base/docs/index.rst
index 69bd9b1efb30..36939c29cbbf 100644
--- a/mobile/android/base/docs/index.rst
+++ b/mobile/android/base/docs/index.rst
@@ -9,3 +9,4 @@ Firefox for Android
    uitelemetry
    adjust
    gradle
+   defaultdomains
diff --git a/mobile/android/docs/defaultdomains.rst b/mobile/android/docs/defaultdomains.rst
new file mode 100644
index 000000000000..3f74cecb8b36
--- /dev/null
+++ b/mobile/android/docs/defaultdomains.rst
@@ -0,0 +1,68 @@
+.. -*- Mode: rst; fill-column: 100; -*-
+
+==========================
+ Shipping Default Domains
+==========================
+
+Firefox for Mobile (Android and iOS) ships sets of default content in order to improve the
+first-run experience. There are two primary places where default sets of domains are used: URLBar
+domain auto-completion, and Top Sites suggested thumbnails.
+
+The source of these domains is typically the Alexa top sites lists, global and by-country. Before
+shipping the sets of domains, the lists are sanitized.
+
+Domain Auto-completion
+======================
+
+As you type in the URLBar, Firefox will scan your history and auto-complete previously visited
+domains that match what you have entered. This can make navigating to web sites faster because it
+can avoid significant amounts of typing. During your first few uses, Firefox does not have any
+history and you are forced to type full URLs. Shipping a set of top domains provides a fallback.
+
+The top domains list can be localized, but Firefox will fallback to using en-US as the default for all
+locales that do not provide a specific set. The list can have several hundred domains, but due to
+size concerns, is usually capped to five hundred or less.
+
+Sanitizing Methods
+------------------
+
+After getting a source list, e.g. Alexa top global sites, we apply some simple guidelines to the
+list of domains:
+
+* Remove any locale-specific domain duplicates. We assume primary URLs (.com) will redirect to the
+  correct locale (.co.jp) at run-time.
+* Remove any explicit adult content domains.
+* Remove any sites that use explicit or adult advertising.
+* Remove any URL shorteners and redirecters.
+* Remove any content/CDN domains. Some sites use separate domains to store images and other
+  static content.
+* Remove any sites primarily used for advertising or management of advertising.
+* Remove any sites that fail to load in mobile browsers.
+* Remove any time/date specific sites that may have appeared on the list due to seasonal spikes.
+
+Suggested Sites
+===============
+
+Suggested sites are default thumbnails, displayed on the Top Sites home panel. A suggested site
+consists of a title, thumbnail image, background color and URL. Multiple images are usually
+required to handle the variety of device DPIs.
+
+Suggested sites can be localized, but Firefox will fallback to using en-US as the default for all
+locales that do not provide a specific set. The list is usually small, with perhaps fewer than ten
+sites.
+
+Sanitizing Methods
+------------------
+
+After getting a source list, e.g. Alexa top global sites, we apply some simple guidelines to the
+list of domains:
+
+* Remove pure search engines. We handle search engines differently and don't consider them to be
+  suggested sites.
+* Remove any locale-specific domain duplicates. We assume primary URLs (.com) will redirect to the
+  correct locale (.co.jp) at run-time.
+* Remove any explicit adult content domains.
+* Remove any sites that use explicit or adult advertising.
+* Remove any URL shorteners and redirecters.
+* Remove any content/CDN domains. Some sites use separate domains to store images and other
+  static content.
diff --git a/mobile/android/docs/index.rst b/mobile/android/docs/index.rst
index 2a4ae7f2ec15..cd0d2f31bfb4 100644
--- a/mobile/android/docs/index.rst
+++ b/mobile/android/docs/index.rst
@@ -14,6 +14,7 @@ Contents:
    localeswitching
    uitelemetry
    adjust
+   defaultdomains
 
 Indices and tables
 ==================