Add improved docs

index.js

@@ -41,7 +41,8 @@ const gradeMap = {
  * @param {Counts} counts
  *   Counts from input document.
  * @return {number}
- *   Number representing ease of reading.
+ *   Score representing ease of reading.
+ *
  *   Pass it to `daleChallGradeLevel` to get grade levels.
  */
 export function daleChallFormula(counts) {
@@ -62,12 +63,22 @@ export function daleChallFormula(counts) {
 }
 
 /**
- * Map between a dale–chall score and a U.S. grade level.
+ * Turn a dale–chall score into U.S. grade levels.
  *
  * @param {number} score
- *   Number representing ease of reading.
+ *   Score representing ease of reading.
  * @returns {[number, number]}
  *   Grade levels.
+ *
+ *   |        Score | Corresponding grade level               | Return value     |
+ *   | -----------: | --------------------------------------- | ---------------- |
+ *   |  Less than 5 | Grade 4 and lower                       | `[0, 4]`         |
+ *   |  Less than 6 | Grades 5 and 6                          | `[5, 6]`         |
+ *   |  Less than 7 | Grades 7 and 8                          | `[7, 8]`         |
+ *   |  Less than 8 | Grades 9 and 10                         | `[9, 10]`        |
+ *   |  Less than 9 | Grades 11 and 12                        | `[11, 12]`       |
+ *   | Less than 10 | Grades 13 and 15 (College)              | `[13, 15]`       |
+ *   |       Higher | Grades 16 and higher (College Graduate) | `[16, Infinity]` |
  */
 export function daleChallGradeLevel(score) {
   let floored = Math.floor(score)

readme.md

@@ -8,37 +8,70 @@
 Formula to detect the grade level of text according to the [(revised) Dale–Chall
 readability formula][formula].
 
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`daleChallFormula(counts)`](#dalechallformulacounts)
+    *   [`daleChallGradeLevel(score)`](#dalechallgradelevelscore)
+*   [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!
+
 See [`dale-chall`][list] for a list of words which count as “familiar”.
+All other words are considered “difficult” for this algorithm.
 
 ## 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 dale-chall-formula
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {daleChallFormula, daleChallGradeLevel} from 'https://esm.sh/dale-chall-formula@2'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {daleChallFormula, daleChallGradeLevel} from 'https://esm.sh/dale-chall-formula@2?bundle'
+</script>
+```
+
 ## Use
 
 ```js
 import {daleChallFormula, daleChallGradeLevel} from 'dale-chall-formula'
 
 daleChallFormula({word: 30, sentence: 2, difficultWord: 6}) // => 4.41208
 
-daleChallFormula({word: 30, sentence: 2}) // => 0.744
-
-daleChallFormula() // => NaN
-
-daleChallGradeLevel(daleChallFormula(30, 2, 6)) // => [9, 10]
+daleChallGradeLevel(daleChallFormula({word: 30, sentence: 2, difficultWord: 6})) // => [9, 10]
 ```
 
 ## API
 
-This package exports the following identifiers: `daleChallFormula`,
-`daleChallGradeLevel`.
+This package exports the identifiers `daleChallFormula`, `daleChallGradeLevel`.
 There is no default export.
 
 ### `daleChallFormula(counts)`
@@ -47,11 +80,41 @@ Given the number of words (`word`), the number of sentences (`sentence`), and
 the number of unique unfamiliar words in a document (`difficultWord`), returns
 the score associated with the document.
 
+##### `counts`
+
+Counts from input document.
+
+###### `counts.sentence`
+
+Number of sentences (`number`, required).
+
+###### `counts.word`
+
+Number of words (`number`, required).
+
+###### `counts.difficultWord`
+
+Number of unique unfamiliar words (`number`, default: `0`).
+
+##### Returns
+
+Score representing ease of reading (`number`).
+
+Pass it to `daleChallGradeLevel` to get grade levels.
+
 ### `daleChallGradeLevel(score)`
 
-Given a score, returns the corresponding grade ranges
+Turn a dale–chall score into U.S. grade levels.
+
+###### `score`
 
-|        Score | Corresponding Grade Level               | Return value     |
+Score representing ease of reading.
+
+###### Returns
+
+Grade levels (`[number, number]`).
+
+|        Score | Corresponding grade level               | Return value     |
 | -----------: | --------------------------------------- | ---------------- |
 |  Less than 5 | Grade 4 and lower                       | `[0, 4]`         |
 |  Less than 6 | Grades 5 and 6                          | `[5, 6]`         |
@@ -61,22 +124,42 @@ Given a score, returns the corresponding grade ranges
 | Less than 10 | Grades 13 and 15 (College)              | `[13, 15]`       |
 |       Higher | Grades 16 and higher (College Graduate) | `[16, Infinity]` |
 
+## 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
 *   [`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, 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
 
@@ -102,6 +185,14 @@ Given a score, returns the corresponding grade ranges
 
 [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