Add improved docs

index.js

@@ -67,10 +67,12 @@ const step4 =
   /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/
 
 /**
- * Stem `value`.
+ * Get the stem from a given value.
  *
  * @param {string} value
+ *   Value to stem.
  * @returns {string}
+ *   Stem for `value`
  */
 // eslint-disable-next-line complexity
 export function stemmer(value) {

readme.md

@@ -7,21 +7,58 @@
 
 [Porter stemming algorithm][source].
 
-## Install
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`stemmer(value)`](#stemmervalue)
+*   [CLI](#cli)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [Security](#security)
+*   [License](#license)
+
+## What is this?
+
+This package exposes a stemming algorithm.
+That means it gets a certain string (typically an English word), and turns it
+into a shorter version (a stem), which can then be compared to other stems
+(of other words), to check if they are both (likely) the same term.
+
+## 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.
+## Install
 
-[npm][]:
+This package is [ESM only][esm].
+In Node.js (version 14.14+, 16.0+), install with [npm][]:
 
 ```sh
 npm install stemmer
 ```
 
-## API
+In Deno with [`esm.sh`][esmsh]:
 
-This package exports the following identifiers: `stemmer`.
-There is no default export.
+```js
+import {stemmer} from 'https://esm.sh/stemmer@2'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {stemmer} from 'https://esm.sh/stemmer@2?bundle'
+</script>
+```
+
+## Use
 
 ```js
 import {stemmer} from 'stemmer'
@@ -31,6 +68,23 @@ stemmer('detestable') // => 'detest'
 stemmer('vileness') // => 'vile'
 ```
 
+## API
+
+This package exports the identifier `stemmer`.
+There is no default export.
+
+### `stemmer(value)`
+
+Get the stem from a given value.
+
+###### `value`
+
+Value to stem (`string`, required).
+
+##### Returns
+
+Stem for `value` (`string`).
+
 ## CLI
 
 ```txt
@@ -54,24 +108,44 @@ $ echo "detestable vileness" | stemmer
 # detest vile
 ```
 
+## 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+ and 16.0+.
+It also works in Deno and modern browsers.
+
 ## Related
 
 *   [`stmr.c`](https://github.com/wooorm/stmr.c)
     — C API
 *   [`stmr`](https://github.com/wooorm/stmr)
     — C CLI
 *   [`lancaster-stemmer`](https://github.com/words/lancaster-stemmer)
-    — Lancaster stemming algorithm
+    — lancaster stemming algorithm
 *   [`double-metaphone`](https://github.com/words/double-metaphone)
-    — Double Metaphone implementation
+    — double metaphone algorithm
 *   [`soundex-code`](https://github.com/words/soundex-code)
-    — Fast Soundex implementation
+    — soundex algorithm
 *   [`dice-coefficient`](https://github.com/words/dice-coefficient)
-    — Sørensen–Dice coefficient
+    — sørensen–dice coefficient
 *   [`levenshtein-edit-distance`](https://github.com/words/levenshtein-edit-distance)
-    — Levenshtein edit distance
+    — levenshtein edit distance
 *   [`syllable`](https://github.com/words/syllable)
-    — Syllable count in an English word
+    — syllable count of English words
+
+## Contribute
+
+Yes please!
+See [How to Contribute to Open Source][contribute].
+
+## Security
+
+This package is safe.
 
 ## License
 
@@ -95,6 +169,14 @@ $ echo "detestable vileness" | stemmer
 
 [size]: https://bundlephobia.com/result?p=stemmer
 
+[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