Add improved docs

readme.md

@@ -8,19 +8,58 @@
 Formula to detect the grade level of text according to the [gunning fog
 index][formula].
 
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`gunningFog(counts)`](#gunningfogcounts)
+*   [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 algorithm is based on syllables, whereas some others are not, which means
+it’s tougher to get right and slower to calculate.
+
 See [`syllable`][syllable] for detecting syllables.
 
 ## Install
 
-This package is ESM only: Node 12+ is needed to use it and it must be `import`ed
-instead of `require`d.
-
-[npm][]:
+This package is [ESM only][esm].
+In Node.js (version 14.14+, 16.0+), install with [npm][]:
 
 ```sh
 npm install gunning-fog
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {gunningFog} from 'https://esm.sh/gunning-fog@2'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {gunningFog} from 'https://esm.sh/gunning-fog@2?bundle'
+</script>
+```
+
 ## Use
 
 ```js
@@ -31,40 +70,81 @@ import {gunningFog} from 'gunning-fog'
 // 1 sentence; 13 words; 4 polysillabic words, of which two are jargon, proper
 // nouns, or compound words.
 gunningFog({sentence: 1, word: 13, complexPolysillabicWord: 2})
-// => 11.353846...
+// => 11.35384…
 ```
 
 ## API
 
-This package exports the following identifiers: `gunningFog`.
+This package exports the identifier `gunningFog`.
 There is no default export.
 
 ### `gunningFog(counts)`
 
-Given an object containing the number of words (`word`), the number of sentences
-(`sentence`), and the number of complex (i.e., jargon, proper nouns, compound
-words) polysillabic (three or more syllables) words
-(`complexPolysillabicWord`) in a document, returns the grade level associated
-with the document.
+Given an object containing the number of words (`word`), the number of
+sentences (`sentence`), and the number of complex (i.e., jargon, proper
+nouns, compound words) polysillabic (three or more syllables) words
+(`complexPolysillabicWord`) 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.complexPolysillabicWord`
+
+Number of words that consist of three or more syllables, that are jargon,
+proper nouns, or compound words (`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
 
 *   [`retext-readability`](https://github.com/wooorm/retext-readability)
-    — Complete readability measuring solution
+    — complete readability measuring solution
 *   [`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`](https://github.com/words/flesch)
-    — Uses syllable count
+    — uses syllable count
 *   [`flesch-kincaid`](https://github.com/words/flesch-kincaid)
-    — Like `flesch`; returns U.S. grade levels
+    — like `flesch`; returns U.S. grade levels
 *   [`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
 
@@ -90,6 +170,14 @@ 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