new file mode 100644
--- /dev/null
+++ b/browser/extensions/formautofill/docs/heuristics.rst
@@ -0,0 +1,37 @@
+Form Autofill Heuristics
+========================
+
+Form Autofill Heuristics module is for detecting the field type based on `autocomplete attribute <https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill>`_, `the regular expressions <http://searchfox.org/mozilla-central/source/browser/extensions/formautofill/content/heuristicsRegexp.js>`_ and the customized logic in each parser.
+
+Debugging
+---------
+
+The pref ``extensions.formautofill.heuristics.enabled`` is "true" in default. Set it to "false" could be useful to verify the result of autocomplete attribute.
+
+Dependent APIs
+--------------
+
+``element.getAutocompleteInfo()`` provides the parsed result of ``autocomplete`` attribute which includes the field name and section information defined in `autofill spec <https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill>`_
+
+Regular Expressions
+-------------------
+
+This section is about how the regular expression is applied during parsing fields. All regular expressions are in `heuristicsRegexp.js <https://searchfox.org/mozilla-central/source/browser/extensions/formautofill/content/heuristicsRegexp.js>`_.
+
+Parser Implementations
+----------------------
+
+The parsers are for detecting the field type more accurately based on the near context of a field. Each parser uses ``FieldScanner`` to traverse the interested fields with the result from the regular expressions and adjust each field type when it matches to a grammar.
+
+* _parsePhoneFields
+
+  * related type: ``tel``, ``tel-*``
+
+* _parseAddressFields
+
+  * related type: ``address-line[1-3]``
+
+* _parseCreditCardExpirationDateFields
+
+  * related type: ``cc-exp``, ``cc-exp-month``, ``cc-exp-year``
+

new file mode 100644
--- /dev/null
+++ b/browser/extensions/formautofill/docs/index.rst
@@ -0,0 +1,31 @@
+Form Autofill
+=============
+
+[`Wiki <https://wiki.mozilla.org/Firefox/Features/Form_Autofill>`_] |
+[IRC `#formfill <ircs://irc.mozilla.org:6697/formfill>`_] |
+[Mailing list `autofill@lists.mozilla.org <mailto:autofill@lists.mozilla.org>`_]
+
+Introduction
+------------
+
+Form Autofill saves users time and effort when making online purchases by storing their personal information in a profile and automatically populating form fields when the user requires it.
+
+Our objective is to increase user engagement, satisfaction and retention for frequent online shoppers (those who make an online purchase at least once per month). We believe this can be achieved by enabling users to complete forms and “check out” in e-commerce flows as quickly and securely as possible.
+
+Debugging
+---------
+
+Set the pref ``extensions.formautofill.loglevel`` to "Debug".
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   heuristics
+
+Report Issues
+-------------
+
+If you find any issues about filling a form with incorrect values, please file a `new bug <https://bugzilla.mozilla.org/enter_bug.cgi?product=Toolkit&component=Form%20Autofill>`_ to Toolkit::Form Autofill component or leave a comment in `bug 1405266 <https://bugzilla.mozilla.org/show_bug.cgi?id=1405266>`_.

--- a/browser/extensions/formautofill/moz.build
+++ b/browser/extensions/formautofill/moz.build
@@ -20,10 +20,12 @@ FINAL_TARGET_PP_FILES.features['formauto
 BROWSER_CHROME_MANIFESTS += ['test/browser/browser.ini']
 
 XPCSHELL_TESTS_MANIFESTS += ['test/unit/xpcshell.ini']
 
 MOCHITEST_MANIFESTS += ['test/mochitest/mochitest.ini']
 
 JAR_MANIFESTS += ['jar.mn']
 
+SPHINX_TREES['docs'] = 'docs'
+
 with Files('**'):
     BUG_COMPONENT = ('Toolkit', 'Form Autofill')