Rework docs

Author: davidkyle

docs/reference/ml/ml-shared.asciidoc

@@ -863,9 +863,10 @@ example, `1575402236000 `.
 end::model-snapshot-id[]
 
 tag::model-snapshot-retention-days[]
-The time in days that model snapshots are retained for the job. Older snapshots
-are deleted. The default value is `1`, which means snapshots are retained for
-one day (twenty-four hours).
+Advanced configuration option. Denotes the period for which model snapshots
+will be retained. Age is calculated as the time from the newest model snapshot's
+timestamp, older snapshots are automatically deleted. The default value is `1`,
+which means snapshots are retained for one day (twenty-four hours).
 end::model-snapshot-retention-days[]
 
 tag::multivariate-by-fields[]
@@ -964,10 +965,10 @@ end::results-index-name[]
 
 tag::results-retention-days[]
 Advanced configuration option. When set this option will prune results older
-than a certain age. The age of a result is calculated as the time difference
-from the result to the latest result. Once per day at 00:30 (server time),
-results older than this period are deleted from {es}. The default value is
-null, which means all results are retained.
+than this age. Age is calculated as the difference between the latest
+bucket result's timestamp and the result's timestamp. Once per day at 00:30
+(server time), results older than this are deleted from {es}. The default
+value is null, which means all results are retained.
 end::results-retention-days[]
 
 tag::retain[]