diff --git a/doc/guides/dts/index.rst b/doc/guides/dts/index.rst
index 7e03e7bb83a..174ec299959 100644
--- a/doc/guides/dts/index.rst
+++ b/doc/guides/dts/index.rst
@@ -449,6 +449,71 @@ Below is a template that shows the format of binding files, stored in
 .. literalinclude:: ../../../dts/binding-template.yaml
    :language: yaml
 
+.. _legacy_binding_syntax:
+
+Legacy binding syntax
+=====================
+
+Various parts of the binding syntax were simplified and generalized for the
+Zephyr 2.1 release.
+
+The binding below shows various legacy syntax.
+
+.. code-block:: yaml
+
+   title: ...
+   description: ...
+
+   inherits:
+       !include foo.yaml
+
+   parent:
+       bus: spi
+
+   properties:
+       compatible:
+           constraint: "company,device"
+           type: string-array
+
+       frequency:
+           type: int
+           category: optional
+
+   sub-node:
+       properties:
+           child-prop:
+               type: int
+               category: required
+
+This should now be written like this:
+
+.. code-block:: yaml
+
+   title: ...
+   description: ...
+
+   compatible: "company,device"
+
+   include: foo.yaml
+
+   parent-bus: spi
+
+   properties:
+       frequency:
+           type: int
+           required: false
+
+   child-node:
+       title: ...
+       description: ...
+
+       properties:
+           child-prop:
+               type: int
+               required: true
+
+The legacy syntax is still supported for backwards compatibility, but generates
+deprecation warnings. Support will be dropped in the Zephyr 2.3 release.
 
 Include files generation
 ************************
diff --git a/doc/releases/release-notes-2.0.rst b/doc/releases/release-notes-2.0.rst
index e9c33597881..5e977096f97 100644
--- a/doc/releases/release-notes-2.0.rst
+++ b/doc/releases/release-notes-2.0.rst
@@ -448,6 +448,27 @@ Bluetooth
 Build and Infrastructure
 ************************
 
+* The devicetree Python scripts have been rewritten to be more robust and
+  easier to understand and change. The new scripts are these three files:
+
+  - :zephyr_file:`scripts/dts/dtlib.py` -- a low-level :file:`.dts` parsing
+    library
+
+  - :zephyr_file:`scripts/dts/edtlib.py` -- a higher-level library that adds
+    information from bindings
+
+  - :zephyr_file:`scripts/dts/gen_defines.py` -- generates a C header from the
+    devicetree files for the board
+
+  The new scripts verify ``category: optional/required`` and ``type:`` settings
+  given in bindings for nodes, and add some new types, like ``phandle-array``.
+  Error messages and other output is now more helpful.
+
+  See the updated documentation in :zephyr_file:`dts/binding-template.yaml`.
+
+  The old scripts are kept around to generate a few deprecated ``#define``\ s.
+  They will be removed in the Zephyr 2.2 release.
+
 * Changed ARM Embedded toolchain to default to nano variant of newlib
 
 
diff --git a/doc/releases/release-notes-2.1.rst b/doc/releases/release-notes-2.1.rst
index 6c0f5c887b2..13d5b6b5a3f 100644
--- a/doc/releases/release-notes-2.1.rst
+++ b/doc/releases/release-notes-2.1.rst
@@ -50,6 +50,11 @@ Build and Infrastructure
   Use new functions that utilize eDTS info such as dt_node_reg_addr.
   See :zephyr_file:`scripts/kconfig/kconfigfunctions.py` for details.
 
+* Various parts of the binding format have been simplified. The format is
+  better documented now too.
+
+  See :ref:`legacy_binding_syntax` for more information.
+
 Libraries / Subsystems
 ***********************