Add improved docs

readme.md

@@ -5,20 +5,58 @@
 [![Downloads][downloads-badge]][downloads]
 [![Size][size-badge]][size]
 
-The part of speech tags from the [Brill-tagger][wiki]: 89,539 unique words or
-symbols with one or more [tags][descriptions].
+Part of speech tags from the [Brill-tagger][wiki]: 89 539 unique words or
+symbols with one or more tags.
 
-## Install
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`brill`](#brill-1)
+*   [Data](#data)
+    *   [Capitalization](#capitalization)
+    *   [Descriptions](#descriptions)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [Security](#security)
+*   [License](#license)
+
+## What is this?
+
+This package exposes a lot of words to POS tags.
 
-This package is ESM only: Node 12+ is needed to use it and it must be `import`ed
-instead of `require`d.
+## When should I use this?
 
-[npm][]:
+Use this when you want to do fun things with natural language.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 14.14+, 16.0+), install with [npm][]:
 
 ```sh
 npm install brill
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {brill} from 'https://esm.sh/brill@3'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {brill} from 'https://esm.sh/brill@3?bundle'
+</script>
+```
+
 ## Use
 
 ```js
@@ -38,43 +76,68 @@ console.log(brill.AA) //=> [ 'JJ', 'NN', 'NNP' ]
 
 ## API
 
-This package exports the following identifiers: `brill`.
+This package exports the identifier `brill`.
 There is no default export.
 
 ### `brill`
 
-`brill` exposes an object where the keys are words and the values are a list of
-tags or joined tags (`Record<string>`).
+`brill` exposes a map of words to a list of tags (`Record<string, Array<string>>`).
+
+## Data
 
-## Capitalization
+### Capitalization
 
 Some words are included as all-caps, first-capital, lowercase, or other:
 
 ```js
-var brill = require('brill')
+import {brill} from 'brill'
 
 console.log(brill.THAT) // [ 'TO', 'DT' ]
 console.log(brill.That) // [ 'DT', 'NNP', 'PDT', 'IN', 'RB', 'EX', 'WDT' ]
 console.log(brill.that) // [ 'IN', 'DT', 'NN', 'RB', 'RP', 'UH', 'WP', 'VBP', 'WDT' ]
 ```
 
-It’s recommended to check a given word first in its original form, and second,
-if no tags are found, in its lowercase form.
+It’s recommended to check a word first in its original form first and if it does
+not exist in its lowercase form.
+
+### Descriptions
+
+See [lib/descriptions.js][descriptions].
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports no additional types.
+
+## Compatibility
+
+This package is at least compatible with all maintained versions of Node.js.
+As of now, that is Node.js 14.14+ and 16.0+.
+It also works in Deno and modern browsers.
 
 ## Related
 
 *   [`buzzwords`](https://github.com/words/buzzwords)
-    — List of buzzwords
+    — list of buzzwords
 *   [`fillers`](https://github.com/words/fillers)
-    — List of filler words
+    — list of filler words
 *   [`hedges`](https://github.com/words/hedges)
-    — List of hedge words
+    — list of hedge words
 *   [`profanities`](https://github.com/words/profanities)
-    — List of profane words
+    — list of profane words
 *   [`dale-chall`](https://github.com/words/dale-chall)
-    — List of familiar American-English words
+    — list of familiar American-English words
 *   [`weasels`](https://github.com/words/weasels)
-    — List of weasel words
+    — list of weasel words
+
+## Contribute
+
+Yes please!
+See [How to Contribute to Open Source][contribute].
+
+## Security
+
+This package is safe.
 
 ## License
 
@@ -100,6 +163,14 @@ if no tags are found, in its lowercase form.
 
 [npm]: https://docs.npmjs.com/cli/install
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
+
+[contribute]: https://opensource.guide/how-to-contribute/
+
 [license]: license
 
 [author]: https://wooorm.com