Add improved docs

index.js

@@ -26,7 +26,7 @@ const base = 206.835
  * @param {Counts} counts
  *   Counts from input document.
  * @returns {number}
- *   Result is 120 (every sentence consisting of only two one-syllable words)
+ *   Result is `120` (every sentence consisting of only two one-syllable words)
  *   or lower (including negative values).
  *
  *   The values have the following semantics:

readme.md

@@ -8,45 +8,102 @@
 Formula to detect the grade level of text according to the [Flesch reading
 ease][formula].
 
-See [`syllable`][syllable] for detecting syllables.
+## Contents
 
-## Install
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`flesch(counts)`](#fleschcounts)
+*   [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?
+
+You’re probably dealing with natural language, and know you need this, if
+you’re here!
 
-This package is ESM only: Node 12+ is needed to use it and it must be `import`ed
-instead of `require`d.
+This algorithm is based on syllables, whereas some others are not, which means
+it’s tougher to get right and slower to calculate.
 
-[npm][]:
+See [syllable][] for detecting syllables.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 14.14+, 16.0+), install with [npm][]:
 
 ```sh
 npm install flesch
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {flesch} from 'https://esm.sh/flesch@2'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {flesch} from 'https://esm.sh/flesch@2?bundle'
+</script>
+```
+
 ## Use
 
 ```js
 import {flesch} from 'flesch'
 
 // For “The cat sat on the mat” (1 sentence, 6 words, 6 syllables).
-flesch({sentence: 1, word: 6, syllable: 6}) // => 116.14500...
+flesch({sentence: 1, word: 6, syllable: 6}) // => 116.14500…
 
 // For “The Australian platypus is seemingly a hybrid of mammal and reptilian
 // creature.” (1 sentence, 12 words, 23 syllables).
-flesch({sentence: 1, word: 12, syllable: 23}) // => 32.50499...
+flesch({sentence: 1, word: 12, syllable: 23}) // => 32.50499…
 ```
 
 ## API
 
-This package exports the following identifiers: `flesch`.
+This package exports the identifier `flesch`.
 There is no default export.
 
 ### `flesch(counts)`
 
-Given an object containing the number of words (`word`), the number of sentences
-(`sentence`), and the number of syllables  (`syllable`) in a document, returns
-the reading ease associated with the document.
+Given an object containing the number of words (`word`), the number of
+sentences (`sentence`), and the number of syllables  (`syllable`) in a
+document, returns the reading ease associated with the document.
+
+##### `counts`
+
+Counts from input document.
+
+###### `counts.sentence`
 
-Returned values are 120 (every sentence consisting of only two one-syllable
-words), or lower (including negative values).
+Number of sentences (`number`, required).
+
+###### `counts.word`
+
+Number of words (`number`, required).
+
+###### `counts.syllable`
+
+Number of syllables (`number`, required).
+
+##### Returns
+
+Result is `120` (every sentence consisting of only two one-syllable words) or
+lower (including negative values).
 
 The values have the following semantics:
 
@@ -60,25 +117,45 @@ Therefore we can use the following formula to approximate the average age a
 student would understand a document at, given score `score`:
 
 ```js
-var age = 20 - Math.floor(score / 10)
+const age = 20 - Math.floor(score / 10)
 ```
 
+## 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
 *   [`coleman-liau`](https://github.com/words/coleman-liau)
-    — Uses letter count instead of an error-prone syllable parser
+    — uses letter count instead of an 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-kincaid`](https://github.com/words/flesch-kincaid)
-    — Like `flesch`, returns U.S. grade levels
+    — like `flesch`, returns U.S. grade levels
 *   [`gunning-fog`](https://github.com/words/gunning-fog)
-    — Uses syllable count, needs POS-tagging and NER
+    — uses syllable count, needs POS-tagging and NER
 *   [`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
 
@@ -104,6 +181,14 @@ var age = 20 - Math.floor(score / 10)
 
 [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