Add improved docs

readme.md

@@ -5,22 +5,55 @@
 [![Downloads][downloads-badge]][downloads]
 [![Size][size-badge]][size]
 
-Easy access to [AFINN-96][afinn96].
+[AFINN-96][].
 
-AFINN 96 is the lightweight (1468 words/phrases) and older version of
-[AFINN 165][afinn165] (3382 words/phrases).
+## Contents
 
-## Install
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`afinn96`](#afinn96)
+*   [Musings](#musings)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [Security](#security)
+*   [License](#license)
+
+## What is this?
 
-This package is ESM only: Node 12+ is needed to use it and it must be `import`ed
-instead of `require`d.
+This package gives you easy access to [AFINN-96][].
 
-[npm][]:
+## When should I use this?
+
+You should likely use [`afinn-165`][afinn-165] instead.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 14.14+, 16.0+), install with [npm][]:
 
 ```sh
 npm install afinn-96
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {afinn96} from 'https://esm.sh/afinn-96@2'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {afinn96} from 'https://esm.sh/afinn-96@2?bundle'
+</script>
+```
+
 ## Use
 
 ```js
@@ -32,14 +65,14 @@ afinn96['fed up'] // => -3
 
 ## API
 
-This package exports the following identifiers: `afinn96`.
+This package exports the identifier `afinn96`.
 There is no default export.
 
 ### `afinn96`
 
-`afinn-96` returns entries to valence ratings (`Object.<number>`).
+`afinn-96` maps entries to valence ratings (`Record<string, number>`).
 
-> Note!
+> 👉 **Note**:
 > Be careful when accessing unknown properties on the `afinn-96` object, words
 > such as `constructor` or `toString` might occur.
 > It’s recommended to use a `hasOwnProperty` check beforehand.
@@ -48,25 +81,45 @@ There is no default export.
 
 Note the AFINN entries are:
 
-*   All lower case
-*   Can contain spaces (cases: `can't stand`, `cashing in`,
+*   all lower case
+*   can contain spaces (cases: `can't stand`, `cashing in`,
     `cool stuff`, `does not work`, `dont like`, `fed up`, `green wash`,
     `green washing`, `messing up`, `no fun`, `not good`, `not working`,
     `right direction`, `screwed up`, `some kind`)
-*   Can contain apostrophes (only case: `can't stand`)
-*   Can contain dashes (cases: `cover-up`, `made-up`, `short-sighted`,
+*   can contain apostrophes (only case: `can't stand`)
+*   can contain dashes (cases: `cover-up`, `made-up`, `short-sighted`,
     `short-sightedness`, `son-of-a-bitch`)
 
+## 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+, 16.0+, and 18.0+.
+It also works in Deno and modern browsers.
+
 ## Related
 
 *   [`afinn-111`](https://github.com/words/afinn-111)
     — AFINN list from 2011, containing 2477 entries
 *   [`afinn-165`](https://github.com/words/afinn-165)
     — AFINN list from 2015, containing 3382 entries
 *   [`emoji-emotion`](https://github.com/words/emoji-emotion)
-    — Like AFINN, but for emoji
+    — like AFINN, but for emoji
 *   [`polarity`](https://github.com/words/polarity)
-    — Detect the polarity of text, based on `afinn-165` and `emoji-emotion`
+    — detect the polarity of text, based on `afinn-165` and `emoji-emotion`
+
+## Contribute
+
+Yes please!
+See [How to Contribute to Open Source][contribute].
+
+## Security
+
+This package is safe.
 
 ## License
 
@@ -92,10 +145,18 @@ Note the AFINN entries are:
 
 [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
 
-[afinn96]: https://www2.imm.dtu.dk/pubdb/views/publication_details.php?id=6010
+[afinn-96]: https://www2.imm.dtu.dk/pubdb/views/publication_details.php?id=6010
 
-[afinn165]: https://github.com/words/afinn-165
+[afinn-165]: https://github.com/words/afinn-165