diff --git a/docs/_functions/domain/DefaultTTL.md b/docs/_functions/domain/DefaultTTL.md
index a22e874d3..3388a5c57 100644
--- a/docs/_functions/domain/DefaultTTL.md
+++ b/docs/_functions/domain/DefaultTTL.md
@@ -12,9 +12,12 @@ it will use the DNSControl global default of 300 seconds.
 
 D("example.com", REGISTRAR, DnsProvider("R53"),
   DefaultTTL(2000),
-  A("@","1.2.3.4"), //has default
-  A("foo", "2.3.4.5", TTL(500)) //overrides default
+  A("@","1.2.3.4"), // uses default
+  A("foo", "2.3.4.5", TTL(500)) // overrides default
 );
 
+The DefaultTTL duration can take the same values as [TTL](#TTL):
+an integer number of seconds or a string with a unit such as `"4d"`.
+
 {%endhighlight%}
-{% include endExample.html %}
\ No newline at end of file
+{% include endExample.html %}
diff --git a/docs/_functions/record/TTL.md b/docs/_functions/record/TTL.md
index 425924d22..38edb2a6a 100644
--- a/docs/_functions/record/TTL.md
+++ b/docs/_functions/record/TTL.md
@@ -7,14 +7,30 @@ parameters:
 TTL sets the TTL for a single record only. This will take precedence
 over the domain's [DefaultTTL](#DefaultTTL) if supplied.
 
+The value can be:
+
+  * An integer (number of seconds). Example: `600`
+  * A string: Integer with single-letter unit: Example: `5m`
+  * The unit denotes:
+    * s (seconds)
+    * m (minutes)
+    * h (hours)
+    * d (days)
+    * w (weeks)
+    * n (nonths) (30 days in a nonth)
+    * y (years) (If you set a TTL to a year, we assume you also do crossword puzzles in pen. Show off!)
+    * If no unit is specified, the default is seconds.
+  * We highly recommend using units instead of the number of seconds. Would your coworkers understand your intention better if you wrote 14400 or "4h"?
+
 {% include startExample.html %}
 {% highlight js %}
 
 D("example.com", REGISTRAR, DnsProvider("R53"),
   DefaultTTL(2000),
-  A("@","1.2.3.4"), //has default
-  A("foo", "2.3.4.5", TTL(500)) //overrides default
+  A("@","1.2.3.4"), // uses default
+  A("foo", "2.3.4.5", TTL(500)), // overrides default
+  A("demo1", "3.4.5.11", TTL("5d")),  // 5 days
+  A("demo2", "3.4.5.12", TTL("5w")),  // 5 weeks
 );
-
 {%endhighlight%}
-{% include endExample.html %}
\ No newline at end of file
+{% include endExample.html %}