6 files changed, 77 insertions, 17 deletions
diff --git a/docs/getting_started.md b/docs/getting_started.md
index 159d3de64..7737f08d7 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -3,7 +3,9 @@
 In this chapter we'll discuss:
 
 - Installing Deno
+- Setting up your environment
 - Running a simple `Hello World` script
 - Writing our own script
+- Understanding permissions
 - Using Deno with TypeScript
 - Using WebAssembly
diff --git a/docs/getting_started/first_steps.md b/docs/getting_started/first_steps.md
index 4b3dd5108..9186af730 100644
--- a/docs/getting_started/first_steps.md
+++ b/docs/getting_started/first_steps.md
@@ -14,7 +14,7 @@ before attempting to start with Deno.
 Deno is a runtime for JavaScript/TypeScript which tries to be web compatible and
 use modern features wherever possible.
 
-Browser compatibility means, a simple `Hello World` program in Deno is the same
+Browser compatibility means a simple `Hello World` program in Deno is the same
 as the one you can run in the browser:
 
 ```ts
@@ -87,9 +87,9 @@ In this program each command-line argument is assumed to be a filename, the file
 is opened, and printed to stdout.
 
 ```ts
-for (let i = 0; i < Deno.args.length; i++) {
-  let filename = Deno.args[i];
-  let file = await Deno.open(filename);
+const filenames = Deno.args;
+for (const filename of filenames) {
+  const file = await Deno.open(filename);
   await Deno.copy(file, Deno.stdout);
   file.close();
 }
@@ -112,8 +112,10 @@ This is an example of a simple server which accepts connections on port 8080,
 and returns to the client anything it sends.
 
 ```ts
-const listener = Deno.listen({ port: 8080 });
-console.log("listening on 0.0.0.0:8080");
+const hostname = "0.0.0.0";
+const port = 8080;
+const listener = Deno.listen({ hostname, port });
+console.log(`Listening on ${hostname}:${port}`);
 for await (const conn of listener) {
   Deno.copy(conn, conn);
 }
diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md
index 158e18133..7d39e4251 100644
--- a/docs/getting_started/installation.md
+++ b/docs/getting_started/installation.md
@@ -59,11 +59,22 @@ Use `deno help` to see help text documenting Deno's flags and usage. Use
 
 ### Updating
 
-To update a previously installed version of Deno, you can run `deno upgrade`.
+To update a previously installed version of Deno, you can run:
+
+```shell
+deno upgrade
+```
+
 This will fetch the latest release from
 [github.com/denoland/deno/releases](https://github.com/denoland/deno/releases),
 unzip it, and replace your current executable with it.
 
+You can also use this utility to install a specific version of Deno:
+
+```shell
+deno upgrade --version 1.0.1
+```
+
 ### Building from source
 
 Information about how to build from source can be found in the `Contributing`
diff --git a/docs/getting_started/permissions.md b/docs/getting_started/permissions.md
index c5880225a..317d85046 100644
--- a/docs/getting_started/permissions.md
+++ b/docs/getting_started/permissions.md
@@ -1,15 +1,50 @@
 ## Permissions
 
-<!-- TODO(lucacasonato): what are permissions -->
+Deno is secure by default. Therefore, unless you specifically enable it, a deno
+module has no file, network, or environment access for example. Access to
+security sensitive areas or functions requires the use of permissions to be
+granted to a deno process on the command line.
 
-<!-- TODO(lucacasonato): description of all permissions -->
+For the following example, `mod.ts` has been granted read-only access to the
+file system. It cannot write to it, or perform any other security sensitive
+functions.
+
+```shell
+deno run --allow-read mod.ts
+```
+
+### Permissions list
+
+The following permissions are available:
+
+- **-A, --allow-all** Allow all permissions. This disables all security.
+- **--allow-env** Allow environment access for things like getting and setting
+  of environment variables.
+- **--allow-hrtime** Allow high resolution time measurement. High resolution
+  time can be used in timing attacks and fingerprinting.
+- **--allow-net=\<allow-net\>** Allow network access. You can specify an
+  optional, comma separated list of domains to provide a whitelist of allowed
+  domains.
+- **--allow-plugin** Allow loading plugins. Please note that --allow-plugin is
+  an unstable feature.
+- **--allow-read=\<allow-read\>** Allow file system read access. You can specify
+  an optional, comma separated list of directories or files to provide a
+  whitelist of allowed file system access.
+- **--allow-run** Allow running subprocesses. Be aware that subprocesses are not
+  run in a sandbox and therefore do not have the same security restrictions as
+  the deno process. Therefore, use with caution.
+- **--allow-write=\<allow-write\>** Allow file system write access. You can
+  specify an optional, comma separated list of directories or files to provide a
+  whitelist of allowed file system access.
 
 ### Permissions whitelist
 
-Deno also allows you to control the granularity of permissions with whitelists.
+Deno also allows you to control the granularity of some permissions with
+whitelists.
 
 This example restricts file system access by whitelisting only the `/usr`
-directory:
+directory, however the execution fails as the process was attempting to access a
+file in the `/etc` directory:
 
 ```shell
 $ deno run --allow-read=/usr https://deno.land/std/examples/cat.ts /etc/passwd
@@ -41,6 +76,9 @@ This is an example on how to whitelist hosts/urls:
 $ deno run --allow-net=github.com,deno.land fetch.ts
 ```
 
+If `fetch.ts` tries to establish network connections to any other domain, the
+process will fail.
+
 Allow net calls to any host/url:
 
 ```shell
diff --git a/docs/getting_started/setup_your_environment.md b/docs/getting_started/setup_your_environment.md
index a0d04b385..70bcb5821 100644
--- a/docs/getting_started/setup_your_environment.md
+++ b/docs/getting_started/setup_your_environment.md
@@ -8,8 +8,8 @@ IDE of choice.
 
 There are several env vars that control how Deno behaves:
 
-`DENO_DIR` defaults to `$HOME/.deno` but can be set to any path to control where
-generated and cached source code is written and read to.
+`DENO_DIR` defaults to `$HOME/.cache/deno` but can be set to any path to control
+where generated and cached source code is written and read to.
 
 `NO_COLOR` will turn off color output if set. See https://no-color.org/. User
 code can test if `NO_COLOR` was set without having `--allow-env` by using the
diff --git a/docs/getting_started/typescript.md b/docs/getting_started/typescript.md
index 197c41482..7689273db 100644
--- a/docs/getting_started/typescript.md
+++ b/docs/getting_started/typescript.md
@@ -2,12 +2,19 @@
 
 <!-- TODO(lucacasonato): text on 'just import .ts' -->
 
-### Using external type definitions
-
 Deno supports both JavaScript and TypeScript as first class languages at
 runtime. This means it requires fully qualified module names, including the
 extension (or a server providing the correct media type). In addition, Deno has
-no "magical" module resolution.
+no "magical" module resolution. Instead, imported modules are specified as files
+(including extensions) or fully qualified URL imports. Typescript modules can be
+directly imported. E.g.
+
+```
+import { Response } from "https://deno.land/std@0.53.0/http/server.ts";
+import { queue } from "./collections.ts";
+```
+
+### Using external type definitions
 
 The out of the box TypeScript compiler though relies on both extension-less
 modules and the Node.js module resolution logic to apply types to JavaScript
@@ -98,7 +105,7 @@ way to support customization a configuration file such as `tsconfig.json` might
 be provided to Deno on program execution.
 
 You need to explicitly tell Deno where to look for this configuration by setting
-the `-c` argument when executing your application.
+the `-c` (or `--config`) argument when executing your application.
 
 ```shell
 deno run -c tsconfig.json mod.ts