Add improved docs

readme.md

@@ -8,17 +8,56 @@
 Formula to detect the ease of reading a text according to the [Coleman-Liau
 index][formula].
 
-## Install
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`colemanLiau(counts)`](#colemanliaucounts)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [Security](#security)
+*   [License](#license)
+
+## What is this?
+
+This package exposes an algorithm to detect ease of reading of English texts.
+
+## When should I use this?
 
-This package is ESM only: Node 12+ is needed to use it and it must be `import`ed
-instead of `require`d.
+You’re probably dealing with natural language, and know you need this, if
+you’re here!
 
-[npm][]:
+This algorithm isn’t based on syllabbles compared to some other algorithms,
+which means it’s quicker to calculate.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 14.14+, 16.0+), install with [npm][]:
 
 ```sh
 npm install coleman-liau
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {colemanLiau} from 'https://esm.sh/coleman-liau@2'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {colemanLiau} from 'https://esm.sh/coleman-liau@2?bundle'
+</script>
+```
+
 ## Use
 
 ```js
@@ -45,7 +84,7 @@ colemanLiau({sentence: 5, word: 119, letter: 639}) // => 14.53042…
 
 ## API
 
-This package exports the following identifiers: `colemanLiau`.
+This package exports the identifier `colemanLiau`.
 There is no default export.
 
 ### `colemanLiau(counts)`
@@ -54,23 +93,63 @@ Given an object containing the number of words (`word`), the number of sentences
 (`sentence`), and the number of letters  (`letter`) in a document, returns the
 grade level associated with the document.
 
+##### `counts`
+
+Counts from input document.
+
+###### `counts.sentence`
+
+Number of sentences (`number`, required).
+
+###### `counts.word`
+
+Number of words (`number`, required).
+
+###### `counts.letter`
+
+Number of letters (`number`, required).
+
+##### Returns
+
+Grade level associated with the document (`number`).
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional type `Counts`.
+
+## 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
 
 *   [`automated-readability`](https://github.com/words/automated-readability)
-    — Uses character count instead of error-prone syllable parser
+    — uses character count instead of error-prone syllable parser
 *   [`dale-chall-formula`](https://github.com/words/dale-chall-formula)
-    — Uses a dictionary, suited for higher reading levels
+    — uses a dictionary, suited for higher reading levels
 *   [`flesch`](https://github.com/words/flesch)
-    — Uses syllable count
+    — uses syllable count
 *   [`flesch-kincaid`](https://github.com/words/flesch-kincaid)
-    — Like `flesch-formula`, returns U.S. grade levels
+    — like `flesch-formula`, returns U.S. grade levels
 *   [`gunning-fog`](https://github.com/words/gunning-fog)
-    — Uses syllable count, hard to implement with a computer (needs
+    — uses syllable count, hard to implement with a computer (needs
     POS-tagging and Named Entity Recognition)
 *   [`smog-formula`](https://github.com/words/smog-formula)
-    — Like `gunning-fog-index`, without needing advanced NLP
+    — like `gunning-fog-index`, without needing advanced NLP
 *   [`spache-formula`](https://github.com/words/spache-formula)
-    — Uses a dictionary, suited for lower reading levels
+    — uses a dictionary, suited for lower reading levels
+
+## Contribute
+
+Yes please!
+See [How to Contribute to Open Source][contribute].
+
+## Security
+
+This package is safe.
 
 ## License
 
@@ -96,6 +175,14 @@ grade level associated with the document.
 
 [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