1 files changed, 39 insertions, 0 deletions
diff --git a/docs/testing/documentation.md b/docs/testing/documentation.md
new file mode 100644
index 000000000..f0a2061db
--- /dev/null
+++ b/docs/testing/documentation.md
@@ -0,0 +1,39 @@
+# Documentation tests
+
+Deno supports type-checking your documentation examples.
+
+This makes sure that examples within your documentation are up to date and
+working.
+
+The basic idea is this:
+
+````ts
+/**
+ * # Examples
+ *
+ * ```ts
+ * const x = 42;
+ * ```
+ */
+````
+
+The triple backticks mark the start and end of code blocks.
+
+If this example was in a file named foo.ts, running `deno test --doc foo.ts`
+will extract this example, and then type-check it as a standalone module living
+in the same directory as the module being documented.
+
+To document your exports, import the module using a relative path specifier:
+
+````ts
+/**
+ * # Examples
+ *
+ * ```ts
+ * import { foo } from "./foo.ts";
+ * ```
+ */
+export function foo(): string {
+  return "foo";
+}
+````