diff --git a/doc/device-api.txt b/doc/device-api.txt
index 4265acf..8dff0f8 100644
--- a/doc/device-api.txt
+++ b/doc/device-api.txt
@@ -98,6 +98,13 @@ Properties	string Address [readonly]
 			The Bluetooth remote name. This value can not be
 			changed. Use the Alias property instead.
 
+			This value is only present for completeness. It is
+			better to always use the Alias property when
+			displaying the devices name.
+
+			If the Alias property is unset, it will reflect
+			this value which makes is more convenient.
+
 		uint16 Vendor [readonly] [optional]
 
 			Vendor unique numeric identifier.