new file mode 100644
--- /dev/null
+++ b/build/docs/android-gradle.rst
@@ -0,0 +1,81 @@
+.. _android-gradle:
+
+=========================================
+Android Gradle integration into moz.build
+=========================================
+
+The build system support for building Android packages (APK files) is
+transitioning away from a Makefile-based system and towards a
+Gradle-based system.  Bug 1254353 tracks this transition.
+
+Right now, the Makefile-based system and the Gradle-based system
+coexist, and this document explains how the two systems interact.
+
+The Gradle-based system
+=======================
+
+The original purpose of the Gradle-based system was to allow Fennec
+developers to use IntelliJ or Android Studio to speed up the
+edit-compile-run cycle.  The intention was not to replace the
+Makefile-based system, and most of the choices reflect that.
+
+The Gradle configuration is mostly determined by two parameters:
+
+- ``buildType`` [#buildType]_, either ``debug`` or ``release``, and
+- ``audience`` flavor dimension [#flavorDimension]_, either ``local``,
+  ``localOld``, ``official``.
+
+**The Makefile-based Fennec APK corresponds to the Gradle-based ``officialRelease`` APK.**
+
+The ``release`` build type turns on ProGuard.
+
+The ``official`` flavor dimension turns off developer-specific build
+tweaks, including ``multiDex`` mode.
+
+In particular, ``debug`` builds are not used in Mozilla automation to
+produce APKs (although they are used to build and run tests); and the
+``local`` and ``localOld`` builds are there to support local
+developers.  Everything else is ignored.
+
+Interaction without ``--with-gradle``
+=====================================
+
+When the ``--with-gradle`` flag *is not* in the ``mozconfig``, the
+Gradle integration sits on top of the Makefile-based system.  The
+developer chooses either a ``local`` (for API 21+ devices) or a
+``localOld`` (for API <21 devices) build configuration.  The main
+``mach build && mach package`` steps are augmented by IDE-specific
+invocations that let Android Studio:
+
+- rebuild ``AndroidManifest.xml`` if necessary;
+- compile modified Java;
+- update modified resources and assets;
+- rebuild ``omni.ja`` if any JavaScript or chrome XHTML/CSS has
+  changed;
+
+before producing a new APK (separate from the Makefile-based APK).
+This Gradle-produced APK *includes* the Gecko libraries (``libxul.so``,
+``libmozglue.so``, etc) so it can be deployed to device (from within
+an IDE, or directly by Gradle).
+
+The ``android-api-15`` task in automation exercises this flow.
+
+Interaction with ``--with-gradle``
+==================================
+
+When the ``--with-gradle`` flag *is* in the ``mozconfig``, the
+Makefile-based system invokes Gradle itself to produce a Fennec APK.
+The Makefile-based system invokes Gradle to build the
+``officialRelease`` APK to complete the ``mach build`` process; the
+resulting Gradle APK *does not* include Gecko libraries
+(``libxul.so``, ``libmozglue.so``, etc) so it *cannot* be deployed to
+device (from within an IDE, or directly by Gradle).  (Technically it
+can be deployed, but it cannot be launched: it will crash immediately
+due to the missing native libraries.)  The ``mach package`` process
+will insert the required libraries into the Gradle-produced APK and
+``mach install`` will deploy it to device.
+
+The ``android-api-15-gradle`` task in automation exercises this flow.
+
+.. [#buildType] http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Build-Types
+.. [#flavorDimension] http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Multi-flavor-variants

--- a/build/docs/index.rst
+++ b/build/docs/index.rst
@@ -22,23 +22,23 @@ Important Concepts
    test_manifests
    mozinfo
    preprocessor
    jar-manifests
    defining-binaries
    toolchains
    locales
    rust
+   android-gradle
 
 integrated development environment (IDE)
 ========================================
 .. toctree::
    :maxdepth: 1
 
-   androideclipse
    cppeclipse
    visualstudio
 
 mozbuild
 ========
 
 mozbuild is a Python package containing a lot of the code for the
 Mozilla build system.