adjust docs (#5598)

docs/linking_to_external_code.md

@@ -1,6 +1,6 @@
 # Linking to third party code
 
-In the [Getting Started](./getting_started.md) section, we saw that Deno could
+In the [Getting Started](./getting_started.md) section, we saw Deno could
 execute scripts from URLs. Like browser JavaScript, Deno can import libraries
 directly from URLs. This example uses a URL to import an assertion library:
 
@@ -29,10 +29,10 @@ and yet it accessed the network. The runtime has special access to download
 imports and cache them to disk.
 
 Deno caches remote imports in a special directory specified by the `$DENO_DIR`
-environmental variable. It defaults to the system's cache directory if
+environment variable. It defaults to the system's cache directory if `$DENO_DIR`
-`$DENO_DIR` is not specified. The next time you run the program, no downloads
+is not specified. The next time you run the program, no downloads will be made.
-will be made. If the program hasn't changed, it won't be recompiled either. The
+If the program hasn't changed, it won't be recompiled either. The default
-default directory is:
+directory is:
 
 - On Linux/Redox: `$XDG_CACHE_HOME/deno` or `$HOME/.cache/deno`
 - On Windows: `%LOCALAPPDATA%/deno` (`%LOCALAPPDATA%` = `FOLDERID_LocalAppData`)

docs/linking_to_external_code/import_maps.md

@@ -5,7 +5,7 @@
 
 Deno supports [import maps](https://github.com/WICG/import-maps).
 
-You can use import map with the `--importmap=<FILE>` CLI flag.
+You can use import maps with the `--importmap=<FILE>` CLI flag.
 
 Current limitations:
 

docs/linking_to_external_code/proxies.md

@@ -1,9 +1,9 @@
 ## Proxies
 
-Deno supports proxies for module downloads and `fetch` API.
+Deno supports proxies for module downloads and the Web standard `fetch` API.
 
 Proxy configuration is read from environmental variables: `HTTP_PROXY` and
 `HTTPS_PROXY`.
 
-In case of Windows if environmental variables are not found Deno falls back to
+In case of Windows, if environment variables are not found Deno falls back to
 reading proxies from registry.

docs/linking_to_external_code/reloading_modules.md

@@ -19,4 +19,4 @@ comma to separate URLs
 
 `--reload=https://deno.land/std/fs/copy.ts,https://deno.land/std/fmt/colors.ts`
 
-<!-- Should this be part of examples? --
+<!-- Should this be part of examples? -->

docs/runtime/compiler_apis.md

@@ -19,7 +19,7 @@ fully qualified module name, and the value is the text source of the module. If
 not attempt to resolve them outside of Deno. If `sources` are not provided, Deno
 will resolve modules as if the root module had been passed on the command line.
 Deno will also cache any of these resources. All resolved resources are treated
-as dynamic imports and require read or net permissions depending if they're
+as dynamic imports and require read or net permissions depending on if they're
 local or remote. The `options` argument is a set of options of type
 `Deno.CompilerOptions`, which is a subset of the TypeScript compiler options
 containing the ones supported by Deno.

docs/runtime/program_lifecycle.md

@@ -3,8 +3,8 @@
 Deno supports browser compatible lifecycle events: `load` and `unload`. You can
 use these events to provide setup and cleanup code in your program.
 
-Listener for `load` events can be asynchronous and will be awaited. Listener for
+Listeners for `load` events can be asynchronous and will be awaited. Listeners
-`unload` events need to be synchronous. Both events cannot be cancelled.
+for `unload` events need to be synchronous. Both events cannot be cancelled.
 
 Example:
 
@@ -51,7 +51,7 @@ console.log("log from imported script");
 
 Note that you can use both `window.addEventListener` and
 `window.onload`/`window.onunload` to define handlers for events. There is a
-major difference between them, let's run example:
+major difference between them, let's run the example:
 
 ```shell
 $ deno run main.ts

docs/runtime/stability.md

@@ -1,10 +1,10 @@
 ## Stability
 
-As of Deno 1.0.0, the `Deno` namespace APIs are stable. That means that we will
+As of Deno 1.0.0, the `Deno` namespace APIs are stable. That means we will
 strive to make code working under 1.0.0 continue to work in future versions.
 
 However, not all of Deno's features are ready for production yet. Features which
-are not ready because they are still in draft phase are locked behind the
+are not ready, because they are still in draft phase, are locked behind the
 `--unstable` command line flag. Passing this flag does a few things:
 
 - It enables the use of unstable APIs during runtime.
@@ -14,7 +14,7 @@ are not ready because they are still in draft phase are locked behind the
   This includes the output of `deno types`.
 
 You should be aware that unstable APIs have probably **not undergone a security
-review**, are likely to have **breaking API changes** in the future and are
+review**, are likely to have **breaking API changes** in the future, and are
 **not ready for production**.
 
 Furthermore Deno's standard modules (https://deno.land/std/) are not yet stable.

docs/runtime/workers.md

@@ -7,7 +7,7 @@ Workers can be used to run code on multiple threads. Each instance of `Worker`
 is run on a separate thread, dedicated only to that worker.
 
 Currently Deno supports only `module` type workers; thus it's essential to pass
-`type: "module"` option when creating new worker:
+`type: "module"` option when creating a new worker:
 
 ```ts
 // Good
@@ -66,9 +66,9 @@ hello world
 > This is an unstable Deno feature. Learn more about
 > [unstable features](./stability.md).
 
-By default `Deno` namespace is not available in worker scope.
+By default the `Deno` namespace is not available in worker scope.
 
-To add `Deno` namespace pass `deno: true` option when creating new worker:
+To add the `Deno` namespace pass `deno: true` option when creating new worker:
 
 ```ts
 // main.js
@@ -92,7 +92,7 @@ $ deno run --allow-read --unstable main.js
 hello world
 ```
 
-When `Deno` namespace is available in worker scope; the worker inherits parent
+When the `Deno` namespace is available in worker scope, the worker inherits its
-process permissions (the ones specified using `--allow-*` flags).
+parent process' permissions (the ones specified using `--allow-*` flags).
 
 We intend to make permissions configurable for workers.