Add improved docs

index.js

@@ -225,12 +225,13 @@ const EXPRESSION_DOUBLE = new RegExp(
 // Expression to match triple syllable suffixes.
 const EXPRESSION_TRIPLE = /(creations?|ology|ologist|onomy|onomist)$/g
 
-// Wrapper to support multiple word-parts (GH-11).
 /**
- * Syllable count
+ * Count syllables in `value`.
  *
  * @param {string} value
+ *   Value to check.
  * @returns {number}
+ *   Syllables in `value`.
  */
 export function syllable(value) {
   const values = normalize(String(value))
@@ -251,7 +252,7 @@ export function syllable(value) {
 }
 
 /**
- * Get syllables in a given value.
+ * Get syllables in a word.
  *
  * @param {string} value
  * @returns {number}

readme.md

@@ -5,23 +5,58 @@
 [![Downloads][downloads-badge]][downloads]
 [![Size][size-badge]][size]
 
-Syllable count in JavaScript.
+Count syllables in an English word.
 
-## Install
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`syllable(value)`](#syllablevalue)
+*   [CLI](#cli)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [Security](#security)
+*   [Notice](#notice)
+*   [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 estimates how many syllables are in an English word.
 
-[npm][]:
+## When should I use this?
+
+Use this when you want to do fun things with natural language, like rhyming,
+detecting reading ease, etc.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 14.14+, 16.0+), install with [npm][]:
 
 ```sh
 npm install syllable
 ```
 
-## API
+In Deno with [`esm.sh`][esmsh]:
 
-This package exports the following identifiers: `syllable`.
-There is no default export.
+```js
+import {syllable} from 'https://esm.sh/syllable@5'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {syllable} from 'https://esm.sh/syllable@5?bundle'
+</script>
+```
+
+## Use
 
 ```js
 import {syllable} from 'syllable'
@@ -37,12 +72,29 @@ syllable('wine-bottle') // 3
 syllable('Åland') // 2
 ```
 
+## API
+
+This package exports the identifier `syllable`.
+There is no default export.
+
+### `syllable(value)`
+
+Get the number of syllables in `value`.
+
+###### `value`
+
+Value to check (`string`, required).
+
+##### Returns
+
+Syllables in `value` (`number`).
+
 ## CLI
 
 ```txt
 Usage: syllable [options] <words...>
 
-Syllable count in an English word
+Count syllables in English words
 
 Options:
 
@@ -60,56 +112,76 @@ $ echo "syllable unicorn banana" | syllable
 # 9
 ```
 
-## Inspiration
+## Types
 
-Based on the syllable functionality found in [`Text-Statistics`][stats] (PHP),
-in turn inspired by [`Lingua::EN::Syllable`][lingua] (Perl).
+This package is fully typed with [TypeScript][].
+It exports no additional types.
 
-Support for word-breaks, non-ASCII characters, and many fixes added later.
+## 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)
-    — Formula to detect ease of reading according to the Automated Readability
+    — formula to detect ease of reading according to the Automated Readability
     Index (1967)
 *   [`buzzwords`](https://github.com/words/buzzwords)
-    — List of buzzwords
+    — list of buzzwords
 *   [`coleman-liau`](https://github.com/words/coleman-liau)
-    — Formula to detect the ease of reading a text according to the Coleman-Liau
+    — formula to detect the ease of reading a text according to the Coleman-Liau
     index (1975)
 *   [`cuss`](https://github.com/words/cuss)
-    — Map of profane words to a rating of sureness
+    — map of profane words to a rating of sureness
 *   [`dale-chall`](https://github.com/words/dale-chall)
-    — List of easy American-English words: The New Dale-Chall (1995)
+    — list of easy American-English words: The New Dale-Chall (1995)
 *   [`dale-chall-formula`](https://github.com/words/dale-chall-formula)
-    — Formula to find the grade level according to the (revised) Dale–Chall
+    — formula to find the grade level according to the (revised) Dale–Chall
     Readability Formula (1995)
 *   [`fillers`](https://github.com/words/fillers)
-    — List of filler words
+    — list of filler words
 *   [`flesch`](https://github.com/words/flesch)
-    — Formula to detect the ease of reading a text according to Flesch Reading
+    — formula to detect the ease of reading a text according to Flesch Reading
     Ease (1975)
 *   [`flesch-kincaid`](https://github.com/words/flesch-kincaid)
-    — Formula to detect the grade level of text according to Flesch–Kincaid
+    — formula to detect the grade level of text according to Flesch–Kincaid
     Grade Level (1975)
 *   [`gunning-fog`](https://github.com/words/gunning-fog)
-    — Formula to detect the ease of reading a text according to the Gunning fog
+    — formula to detect the ease of reading a text according to the Gunning fog
     index (1952)
 *   [`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
 *   [`smog-formula`](https://github.com/words/smog-formula)
-    — Formula to detect the ease of reading a text according to the SMOG
+    — formula to detect the ease of reading a text according to the SMOG
     (Simple Measure of Gobbledygook) formula (1969)
 *   [`spache`](https://github.com/words/spache)
-    — List of familiar American-English words (1974)
+    — list of familiar American-English words (1974)
 *   [`spache-formula`](https://github.com/words/spache-formula)
-    — Uses a dictionary, suited for lower reading levels
+    — uses a dictionary, suited for lower reading levels
 *   [`weasels`](https://github.com/words/weasels)
-    — Formula to detect the grade level of text according to the (revised)
+    — formula to detect the grade level of text according to the (revised)
     Spache Readability Formula (1974)
 
+## Contribute
+
+Yes please!
+See [How to Contribute to Open Source][contribute].
+
+## Security
+
+This package is safe.
+
+## Notice
+
+Based on the syllable functionality found in [`Text-Statistics`][stats] (PHP),
+in turn inspired by [`Lingua::EN::Syllable`][lingua] (Perl).
+
+Support for word-breaks, non-ASCII characters, and many fixes added later.
+
 ## License
 
 [MIT][license] © [Titus Wormer][author]
@@ -134,6 +206,14 @@ Support for word-breaks, non-ASCII characters, and many fixes added later.
 
 [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