1 files changed, 22 insertions, 4 deletions
diff --git a/docs/standard_library.md b/docs/standard_library.md
index 67e072768..fd1a5e8e8 100644
--- a/docs/standard_library.md
+++ b/docs/standard_library.md
@@ -9,17 +9,34 @@ Standard library is available at: https://deno.land/std/
 
 Standard library is not yet stable and therefore it is versioned differently
 than Deno. For latest release consult https://deno.land/std/ or
-https://deno.land/std/version.ts.
+https://deno.land/std/version.ts. The standard library is released each time
+Deno is released.
 
 We strongly suggest to always use imports with pinned version of standard
-library to avoid unintended changes.
+library to avoid unintended changes. For example, rather than linking to the
+master branch of code, which may change at any time, potentially causing
+compilation errors or unexpected behavior:
+
+```typescript
+// imports from master, this should be avoided
+import { copy } from "https://deno.land/std/fs/copy.ts";
+```
+
+instead, used a version of the std library which is immutable and will not
+change:
+
+```typescript
+// imports from v0.50.0 of std, never changes
+import { copy } from "https://deno.land/std@0.50.0/fs/copy.ts";
+```
 
 ## Troubleshooting
 
 Some of the modules provided in standard library use unstable Deno APIs.
 
 Trying to run such modules without `--unstable` CLI flag ends up with a lot of
-TypeScript errors suggesting that some APIs on `Deno` namespace do not exist:
+TypeScript errors suggesting that some APIs in the `Deno` namespace do not
+exist:
 
 ```typescript
 // main.ts
@@ -55,4 +72,5 @@ To make sure that API producing error is unstable check
 [`lib.deno.unstable.d.ts`](https://github.com/denoland/deno/blob/master/cli/js/lib.deno.unstable.d.ts)
 declaration.
 
-This problem should be fixed in the near future.
+This problem should be fixed in the near future. Feel free to omit the flag if
+the particular modules you depend on compile successfully without it.