diff --git a/site/content/ytt/docs/develop/how-to-write-schema.md b/site/content/ytt/docs/develop/how-to-write-schema.md
index 5d24b5324..a967df0d1 100644
--- a/site/content/ytt/docs/develop/how-to-write-schema.md
+++ b/site/content/ytt/docs/develop/how-to-write-schema.md
@@ -44,6 +44,17 @@ system_domain: ""
 
 declares the Data Value, with the name `system_domain` to be of type **string** with the default value of an **empty string** (i.e. `""`).
 
+Additionally, a Data Value can also have a **title** and a **description** to make the schema easier to understand.
+
+For example,
+```yaml
+#@data/values-schema
+---
+#@schema/title "The system domain name"
+#@schema/desc "The domain this system will be available at"
+system_domain: ""
+```
+
 ---
 ## Implying Types
 
@@ -279,4 +290,4 @@ honeycomb:
 ---
 ## Next Steps
 
-Once you've declared your Data Values, they can be referenced in `ytt` templates as described in [Using Data Values > Referencing Data Values](how-to-use-data-values.md#referencing-data-values)
\ No newline at end of file
+Once you've declared your Data Values, they can be referenced in `ytt` templates as described in [Using Data Values > Referencing Data Values](how-to-use-data-values.md#referencing-data-values)