Improve readme (denoland/deno_std#117)

Original: https://github.com/denoland/deno_std/commit/6a41189a98e29b0c233f12610220490b6deed608

1 files changed, 21 insertions, 32 deletions

diff --git a/README.md b/README.md
index 3d2f1901b..f0f3a90fc 100644
--- a/README.md
+++ b/README.md
@@ -2,52 +2,41 @@
 
 [![Build Status](https://dev.azure.com/denoland/deno_std/_apis/build/status/denoland.deno_std?branchName=master)](https://dev.azure.com/denoland/deno_std/_build/latest?definitionId=2?branchName=master)
 
-- **[colors](./colors/)**
+These modules do not have external dependencies and they are reviewed by the
+Deno core team. The intention is to have a standard set of high quality code
+that all Deno projects can use fearlessly.
 
-  Modules that generate ANSI color codes for the console.
+Contributions are welcome!
 
-- **[flags](./flags/)**
+## How to use
 
-  Command line arguments parser.
+These modules are tagged in accordance with Deno releases. So, for example, the
+v0.2.6 tag is guaranteed to work with deno v0.2.6.
+You can link to v0.2.6 using the URL `https://deno.land/x/std@v0.2.6/`
 
-- **[log](./log/)**
-
-  Command line logging
-
-- **[media_types](./media_types/)**
-
-  A library for resolving media types (MIME types) and extensions.
-
-- **[mkdirp](./fs/)**
-
-  Make directory branches.
-
-- **[http](./http/)**
-
-  A framework for creating HTTP/HTTPS servers inspired by GoLang.
-
-- **[path](./fs/path)**
-
-  File path manipulation.
-
-- **[testing](./testing/)**
-
-  Testing
+It's strongly recommended that you link to tagged releases rather than the
+master branch. The project is still young and we expect disruptive renames in
+the future.
 
 ## Style Guide
 
+### Use TypeScript
+
 ### Use the term "module" instead of "library" or "package"
 
 For clarity and consistency avoid the terms "library" and "package". Instead use
 "module" to refer to a single JS or TS file and also to refer to a directory of
 TS/JS code.
 
-### Use the filename "mod.ts" as the default entry point to a directory of code
+### Do not use the filename `index.ts` nor `index.js`
+
+Deno does not treat "index.js" or "index.ts" in a special way. By using these
+filenames, it suggests that they can be left out of the module specifier when
+they cannot. This is confusing.
 
-`index.ts` comes with the wrong connotations - and `main.ts` should be reserved
-for executable programs. The filename `mod.ts` follows Rust’s convention, is
-shorter than `index.ts`, and doesn’t come with any preconceived notions about
-how it might work.
+If a directory of code needs a default entry point, use the filename `mod.ts`.
+The filename `mod.ts` follows Rust’s convention, is shorter than `index.ts`, and
+doesn’t come with any preconceived notions about how it might work.
 
 ### Within `deno_std`, do not depend on external code