diff --git a/HISTORY.rst b/HISTORY.rst
index e14be583..85cbdfa8 100644
--- a/HISTORY.rst
+++ b/HISTORY.rst
@@ -16,6 +16,9 @@ PlatformIO 2.0
   repository for LD scripts. Moved common configuration for ESP8266 MCU to
   ``esp8266.flash.common.ld``
   (`issue #379 <https://github.com/platformio/platformio/issues/379>`_)
+* Improved documentation for `Espressif <http://docs.platformio.org/en/latest/platforms/espressif.html>`__
+  development platform: OTA update, custom Flash Size, Upload Speed and CPU
+  frequency
 * Fixed reset method for Espressif NodeMCU (ESP-12E Module)
   (`issue #380 <https://github.com/platformio/platformio/issues/380>`_)
 * Fixed issue with code builder when build path contains spaces
diff --git a/docs/index.rst b/docs/index.rst
index a255736f..b8e05a5a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -95,7 +95,7 @@ Contents
 
 .. toctree::
     :caption: Instruments
-    :maxdepth: 2
+    :maxdepth: 3
 
     Platforms & Boards <platforms/index>
     frameworks/index
diff --git a/docs/platforms/espressif_extra.rst b/docs/platforms/espressif_extra.rst
index af550bbf..d089886f 100644
--- a/docs/platforms/espressif_extra.rst
+++ b/docs/platforms/espressif_extra.rst
@@ -9,8 +9,8 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 
-OTA firmware uploading
-----------------------
+OTA update
+----------
 
 There are 2 options:
 
@@ -24,7 +24,7 @@ There are 2 options:
 
 .. code-block:: ini
 
-   [env:***]
+   [env:myenv]
    ...
    upload_port = IP_ADDRESS_HERE
 
@@ -36,17 +36,17 @@ You can pass additional options/flags to OTA uploader using
 
 .. code-block:: ini
 
-    [env:***]
+    [env:myenv]
     upload_flags = --port=8266
 
-Availalbe flags
+Available flags
 
 * ``--port=ESP_PORT`` ESP8266 ota Port. Default 8266
 * ``--auth=AUTH`` Set authentication password
 * ``--spiffs`` Use this option to transmit a SPIFFS image and do not flash
   the module
 
-For the full list with availalbe options please run
+For the full list with available options please run
 
 .. code-block:: bash
 
@@ -79,6 +79,47 @@ For the full list with availalbe options please run
         -d, --debug         Show debug output. And override loglevel with debug.
         -r, --progress      Show progress output. Does not work for ArduinoIDE
 
+Custom CPU Frequency and Upload Speed
+-------------------------------------
+
+See :ref:`projectconf_board_f_cpu` and :ref:`projectconf_upload_speed` options
+from :ref:`projectconf`
+
+.. code-block:: ini
+
+    [env:myenv]
+    # set frequency to 40MHz
+    board_f_cpu = 40000000L
+
+    upload_speed = 9600
+
+
+Custom Flash Size
+-----------------
+
+The list with preconfigured LD scripts is located in public repository
+`platformio-pkg-ldscripts <https://github.com/platformio/platformio-pkg-ldscripts>`_.
+
+* ``esp8266.flash.512k0.ld`` 512K (no SPIFFS)
+* ``esp8266.flash.512k64.ld`` 512K (64K SPIFFS)
+* ``esp8266.flash.1m64.ld`` 1M (64K SPIFFS)
+* ``esp8266.flash.1m128.ld`` 1M (128K SPIFFS)
+* ``esp8266.flash.1m256.ld`` 1M (256K SPIFFS)
+* ``esp8266.flash.1m512.ld`` 1M (512K SPIFFS)
+* ``esp8266.flash.2m.ld`` 2M (1M SPIFFS)
+* ``esp8266.flash.4m1.ld`` 4M (1M SPIFFS)
+* ``esp8266.flash.4m.ld`` 4M (3M SPIFFS)
+* ``esp8266.flash.8m.ld`` 8M (7M SPIFFS)
+* ``esp8266.flash.16m.ld`` 16M (15M SPIFFS)
+
+To override default LD script please use :ref:`projectconf_build_flags` from
+:ref:`projectconf`.
+
+.. code-block:: ini
+
+    [env:myenv]
+    build_flags = -Wl,-Tesp8266.flash.4m.ld
+
 Examples
 --------
 
diff --git a/docs/projectconf.rst b/docs/projectconf.rst
index da086d04..23571f79 100644
--- a/docs/projectconf.rst
+++ b/docs/projectconf.rst
@@ -176,6 +176,7 @@ is described `here <http://www.nongnu.org/avr-libc/user-manual/>`_.
 The full list of ``board_mcu`` for the popular embedded platforms you can find
 in *Boards* section of :ref:`platforms`. See "Microcontroller" column.
 
+.. _projectconf_board_f_cpu:
 
 ``board_f_cpu``
 ^^^^^^^^^^^^^^^
@@ -209,6 +210,7 @@ To print all available serial ports use :ref:`cmd_serialports` command.
 
 A protocol that "uploader" tool uses to talk to the board.
 
+.. _projectconf_upload_speed:
 
 ``upload_speed``
 ^^^^^^^^^^^^^^^^