docs: Re-organize to clarify intent

This is part of #237

README.md

@@ -2,28 +2,37 @@
 
 > **Source code spell checker**
 
+Finds and corrects spelling mistakes among source code:
+- Fast enough to run on monorepos
+- Low false positives so you can run on PRs
+
 [![Build Status](https://dev.azure.com/crate-ci/crate-ci/_apis/build/status/typos?branchName=master)](https://dev.azure.com/crate-ci/crate-ci/_build/latest?definitionId=11&branchName=master)
 [![codecov](https://codecov.io/gh/crate-ci/typos/branch/master/graph/badge.svg)](https://codecov.io/gh/crate-ci/typos)
 [![Documentation](https://img.shields.io/badge/docs-master-blue.svg)][Documentation]
 ![License](https://img.shields.io/crates/l/typos.svg)
 [![Crates Status](https://img.shields.io/crates/v/typos.svg)](https://crates.io/crates/typos)
 
-## [About](docs/about.md)
-
-## [Install](docs/install.md)
-
-## [Reference](docs/reference.md)
+Dual-licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE)
 
-## [Contribute](CONTRIBUTING.md)
+## Documentation
 
-## License
+- [Installation](#install)
+- [Reference](docs/reference.md)
+- [Comparison with other spell checkers](docs/comparison.md)
+- [Benchmarks](benchsuite/runs)
+- [Design](docs/design.md)
+- [Contribute](CONTRIBUTING.md)
+- [CHANGELOG](CHANGELOG.md)
 
-Licensed under either of
+## Install
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+[Download](https://github.com/crate-ci/typos/releases) a pre-built binary
+(installable via [gh-install](https://github.com/crate-ci/gh-install).
 
-at your option.
+Or use rust to install:
+```bash
+cargo install typos-cli
+```
 
 [Crates.io]: https://crates.io/crates/typos-cli
 [Documentation]: https://docs.rs/typos

docs/about.md → docs/comparison.md

@@ -1,38 +1,4 @@
-# About `typos`
-
-## Design Requirements
-
-Spell checks source code:
-- Requires special word-splitting logic to handle situations like hex (`0xDEADBEEF`), `c\nescapes`, `snake_case`, `CamelCase`, `SCREAMING_CASE`, and maybe `arrow-case`.
-- Each programming language has its own quirks, like abbreviations, lack of word separator (`copysign`), etc
-- Backwards compatibility might require keeping misspelled words.
-- Case for proper nouns is irrelevant.
-
-Checking for errors in a CI:
-- No false-positives.
-- On spelling errors, sets the exit code to fail the CI.
-
-Quick feedback and resolution for developer:
-- Fix errors for the user.
-- Integration into other programs, like editors:
-  - `fork`: easy to call into and provides a stable API, including output format
-  - linking: either in the language of choice or bindings can be made to language of choice.
-
-## Design Trade Offs
-
-### typos uses a blacklist
-
-Blacklist: Known typos that map to their corresponding word
-- Ignores unknown typos
-- Ignores typos that follow c-escapes if they aren't handled correctly
-
-Whitelist: A confidence rating is given for how close a word is to one in the whitelist
-- Sensitive to false positives due to hex numbers and c-escapes
-- Traditional spell checkers use a whitelist.
-
-## Related Spell Checkers
-
-See also [benchmarks](../benchsuite/runs).
+# Related Spell Checkers
 
 |                | typos                 | [bloom42/misspell][misspell-rs] | [client9/misspell][misspell-go] | [codespell] | [scspell3k] |
 |----------------|-----------------------|---------------------------------|---------------------------------|-------------|-------------|
@@ -53,6 +19,8 @@ See also [benchmarks](../benchsuite/runs).
 | API            | Rust / [JSON Lines]   | Rust                            | ?                               | Python      | None        |
 | License        | MIT or Apache         | AGPL                            | MIT                             | GPLv2       | GPLv2       |
 
+See also [benchmarks](../benchsuite/runs).
+
 [JSON Lines]: http://jsonlines.org/
 [scspell3k]: https://github.com/myint/scspell
 [misspell-rs]: https://gitlab.com/bloom42/misspell

docs/design.md

@@ -0,0 +1,32 @@
+# Design
+
+## Requirements
+
+Spell checks source code:
+- Requires special word-splitting logic to handle situations like hex (`0xDEADBEEF`), `c\nescapes`, `snake_case`, `CamelCase`, `SCREAMING_CASE`, and maybe `arrow-case`.
+- Each programming language has its own quirks, like abbreviations, lack of word separator (`copysign`), etc
+- Backwards compatibility might require keeping misspelled words.
+- Case for proper nouns is irrelevant.
+
+Checking for errors in a CI:
+- No false-positives.
+- On spelling errors, sets the exit code to fail the CI.
+
+Quick feedback and resolution for developer:
+- Fix errors for the user.
+- Integration into other programs, like editors:
+  - `fork`: easy to call into and provides a stable API, including output format
+  - linking: either in the language of choice or bindings can be made to language of choice.
+
+## Trade Offs
+
+### typos uses a blacklist
+
+Blacklist: Known typos that map to their corresponding word
+- Ignores unknown typos
+- Ignores typos that follow c-escapes if they aren't handled correctly
+
+Whitelist: A confidence rating is given for how close a word is to one in the whitelist
+- Sensitive to false positives due to hex numbers and c-escapes
+- Traditional spell checkers use a whitelist.
+