diff --git a/doc/driver-model/README.txt b/doc/driver-model/README.txt
index f0276b1b46..b891e8459d 100644
--- a/doc/driver-model/README.txt
+++ b/doc/driver-model/README.txt
@@ -301,6 +301,15 @@ device tree) and probe.
 Platform Data
 -------------
 
+*** Note: platform data is the old way of doing things. It is
+*** basically a C structure which is passed to drivers to tell them about
+*** platform-specific settings like the address of its registers, bus
+*** speed, etc. Device tree is now the preferred way of handling this.
+*** Unless you have a good reason not to use device tree (the main one
+*** being you need serial support in SPL and don't have enough SRAM for
+*** the cut-down device tree and libfdt libraries) you should stay away
+*** from platform data.
+
 Platform data is like Linux platform data, if you are familiar with that.
 It provides the board-specific information to start up a device.
 
@@ -366,8 +375,12 @@ Device Tree
 -----------
 
 While platdata is useful, a more flexible way of providing device data is
-by using device tree. With device tree we replace the above code with the
-following device tree fragment:
+by using device tree. In U-Boot you should use this where possible. Avoid
+sending patches which make use of the U_BOOT_DEVICE() macro unless strictly
+necessary.
+
+With device tree we replace the above code with the following device tree
+fragment:
 
 	red-square {
 		compatible = "demo-shape";
diff --git a/include/dm/platdata.h b/include/dm/platdata.h
index fbc8a6b3ad..6f4f00140e 100644
--- a/include/dm/platdata.h
+++ b/include/dm/platdata.h
@@ -16,6 +16,10 @@
 /**
  * struct driver_info - Information required to instantiate a device
  *
+ * NOTE: Avoid using this except in extreme circumstances, where device tree
+ * is not feasible (e.g. serial driver in SPL where <8KB of SRAM is
+ * available). U-Boot's driver model uses device tree for configuration.
+ *
  * @name:	Driver name
  * @platdata:	Driver-specific platform data
  */
@@ -24,6 +28,11 @@ struct driver_info {
 	const void *platdata;
 };
 
+/**
+ * NOTE: Avoid using these except in extreme circumstances, where device tree
+ * is not feasible (e.g. serial driver in SPL where <8KB of SRAM is
+ * available). U-Boot's driver model uses device tree for configuration.
+ */
 #define U_BOOT_DEVICE(__name)						\
 	ll_entry_declare(struct driver_info, __name, driver_info)