diff --git a/doc/source/developer/components.rst b/doc/source/developer/components.rst
index df9b675d..4f213b83 100644
--- a/doc/source/developer/components.rst
+++ b/doc/source/developer/components.rst
@@ -24,6 +24,60 @@ Components
 
     Ironic no longer supports images created like this.
 
+`diskimage-builder [--dry-run] [--stop-on-failure] [--help] filename.yaml [filename2.yaml...]`
+
+    A YAML defined wrapper over `disk-image-create` and `ramdisk-image-create`.
+
+    To generate kernel+ramdisk pair for use with nova-baremetal, specify the YAML:
+
+    .. code-block:: yaml
+
+        - imagename: deploy.ramdisk
+          ramdisk: true
+          elements:
+          - deploy-baremetal
+
+    Duplicate `imagename` entries are merged into a single entry, allowing customizations over
+    a base image definition. If an `imagename` is missing, the `imagename` from the previous
+    entry is implied:
+
+    .. code-block:: yaml
+
+        # base image definition
+        - imagename: output.qcow
+          elements:
+          - vm
+          - block-device-gpt
+          - ubuntu-minimal
+          debug-trace: 1
+          environment:
+            DIB_IMAGE_SIZE: '10'
+
+        # debug logging customization
+        - imagename: output.qcow
+          debug-trace: 2
+
+        # adding element customization
+        - elements:
+          - devuser
+          environment:
+            DIB_DEV_USER_USERNAME: 'myuser'
+            DIB_DEV_USER_PWDLESS_SUDO: 'Yes'
+            DIB_DEV_USER_AUTHORIZED_KEYS: '/home/myuser/.ssh/id_rsa.pub'
+
+        # resulting image entry which will be built
+        - imagename: output.qcow
+          elements:
+          - vm
+          - block-device-gpt
+          - ubuntu-minimal
+          - devuser
+          debug-trace: 2
+          environment:
+            DIB_DEV_USER_USERNAME: 'myuser'
+            DIB_DEV_USER_PWDLESS_SUDO: 'Yes'
+            DIB_DEV_USER_AUTHORIZED_KEYS: '/home/myuser/.ssh/id_rsa.pub'
+            DIB_IMAGE_SIZE: '10'
 
 `element-info`
 
diff --git a/doc/source/user_guide/building_an_image.rst b/doc/source/user_guide/building_an_image.rst
index 97c9d2fb..fbdb1079 100644
--- a/doc/source/user_guide/building_an_image.rst
+++ b/doc/source/user_guide/building_an_image.rst
@@ -19,6 +19,24 @@ The following command will start our image build (distro must be either
 
 This will create a qcow2 file 'image.qcow2' which can then be booted.
 
+Images can also be defined with YAML and built with the `diskimage-builder`.
+
+With an `image.yaml` file containing:
+
+.. code-block:: yaml
+
+   - elements:
+     - <distro>
+     - vm
+
+An image is built with:
+
+::
+
+   diskimage-builder image.yaml
+
+Run `diskimage-builder --help` full description of the YAML attributes supported.
+
 Elements
 --------
 
@@ -79,6 +97,13 @@ There are currently two defaults:
 
     disk-image-create -o output.qcow vm block-device-gpt ubuntu-minimal
 
+  Or with `diskimage-builder` YAML
+
+  .. code-block:: yaml
+
+    - imagename: output.qcow
+      elements: [vm, block-device-gpt, ubuntu-minimal]
+
 * When not using the ``vm`` element a plain filesystem image, without
   any partitioning, is created.
 
diff --git a/doc/source/user_guide/installation.rst b/doc/source/user_guide/installation.rst
index 2ffe2c79..80a1671a 100644
--- a/doc/source/user_guide/installation.rst
+++ b/doc/source/user_guide/installation.rst
@@ -7,8 +7,8 @@ to keep it separate.  For details, see the installation section in the
 :ref:`dev_install`.
 
 Once installed, you will be able to :doc:`build images
-<building_an_image>` using ``disk-image-create`` and the elements
-included in the main ``diskimage-builder`` repository.
+<building_an_image>` using ``disk-image-create`` or ``diskimage-builder``
+and the elements included in the main ``diskimage-builder`` repository.
 
 
 Requirements