2 files changed, 68 insertions, 0 deletions
diff --git a/docs/typescript/configuration.md b/docs/typescript/configuration.md
index ed5af56d7..752b6da71 100644
--- a/docs/typescript/configuration.md
+++ b/docs/typescript/configuration.md
@@ -197,3 +197,10 @@ The biggest "danger" when doing something like this, is that the type checking
 is significantly looser, and there is no way to validate that you are doing
 sufficient and effective feature detection in your code, which may lead to what
 could be trivial errors becoming runtime errors.
+
+### Using the "types" property
+
+The `"types"` property in `"compilerOptions"` can be used to specify arbitrary
+type definitions to include when type checking a programme. For more information
+on this see
+[Using ambient or global types](./types#using-ambient-or-global-types).
diff --git a/docs/typescript/types.md b/docs/typescript/types.md
index 88317cf25..ba5462dc7 100644
--- a/docs/typescript/types.md
+++ b/docs/typescript/types.md
@@ -101,6 +101,67 @@ When seeing this header, Deno would attempt to retrieve
 `https://example.com/coolLib.d.ts` and use that when type checking the original
 module.
 
+### Using ambient or global types
+
+Overall it is better to use module/UMD type definitions with Deno, where a
+module expressly imports the types it depends upon. Modular type definitions can
+express
+[augmentation of the global scope](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/global-modifying-module-d-ts.html)
+via the `declare global` in the type definition. For example:
+
+```ts
+declare global {
+  var AGlobalString: string;
+}
+```
+
+This would make `AGlobalString` available in the global namespace when importing
+the type definition.
+
+In some cases though, when leveraging other existing type libraries, it may not
+be possible to leverage modular type definitions. Therefore there are ways to
+include arbitrary type definitions when type checking programmes.
+
+#### Using a triple-slash directive
+
+This option couples the type definitions to the code itself. By adding a
+triple-slash `types` directive near the type of a module, type checking the file
+will include the type definition. For example:
+
+```ts
+/// <reference types="./types.d.ts" />
+```
+
+The specifier provided is resolved just like any other specifier in Deno, which
+means it requires an extension, and is relative to the module referencing it. It
+can be a fully qualified URL as well:
+
+```ts
+/// <reference types="https://deno.land/x/pkg@1.0.0/types.d.ts" />
+```
+
+#### Using a `tsconfig.json` file
+
+Another option is to use a `tsconfig.json` file that is configured to include
+the type definitions, by supplying a `"types"` value to the `"compilerOptions"`.
+For example:
+
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "./types.d.ts",
+      "https://deno.land/x/pkg@1.0.0/types.d.ts",
+      "/Users/me/pkg/types.d.ts"
+    ]
+  }
+}
+```
+
+Like the triple-slash reference above, the specifier supplied in the `"types"`
+array will be resolved like other specifiers in Deno. In the case of relative
+specifiers, it will be resolved relative to the path to the `tsconfig.json`.
+
 ### Type Checking Web Workers
 
 When Deno loads a TypeScript module in a web worker, it will automatically type