docs: Call out dictionary model

CONTRIBUTING.md

@@ -27,7 +27,9 @@ Already have an idea?  It might be good to first [create an issue][new issue]
 to propose it so we can make sure we are aligned and lower the risk of having
 to re-work some of it and the discouragement that goes along with that.
 
-### Adding typos
+### Updating the Dictionary
+
+`typos` dictionary is a mapping of typos to a list of possible corrections (see [Design](docs/design.nd)).  To add to the dictionary:
 
 1. Add your type to our data file `crates/typos-dict/assets/words.csv`
 

README.md

@@ -27,6 +27,7 @@ Dual-licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE)
     - [Custom](#custom)
   - [Debugging](#debugging)
 - [Reference](docs/reference.md)
+- [FAQ](#faq)
 - [Comparison with other spell checkers](docs/comparison.md)
 - [Benchmarks](benchsuite/runs)
 - [Design](docs/design.md)
@@ -123,5 +124,25 @@ typos --words
 
 If you need to dig in more, you can enable debug logging with `-v`
 
+## FAQ
+
+### Why was ... not corrected?
+
+tl;dr `typos` doesn't know about it yet
+
+`typos` maintains a list of known typo corrections to keep the false positive
+count low so it can safely run unassisted.
+
+This is in contrast to most spell checking UIs people use where there is a
+known list of valid words.  In this case, the spell checker tries to guess your
+intent by finding the closest-looking word.  It then has a gauge for when a
+word isn't close enough and assumes you know best.  The user has the
+opportunity to verify these corrections and explicitly allow or reject them.
+
+For more on the trade offs of these approaches, see [Design](docs/design.md).
+
+- To correct it locally, see also our [False Positives documentation](#false-positives).
+- To contribute your correction, see [Contribute](CONTRIBUTING.md)
+
 [Crates.io]: https://crates.io/crates/typos-cli
 [Documentation]: https://docs.rs/typos

docs/design.md

@@ -25,8 +25,10 @@ Quick feedback and resolution for developer:
 Corrections: Known misspellings that map to their corresponding dictionary word
 - Ignores unknown typos
 - Ignores typos that follow c-escapes if they aren't handled correctly
+- Good for unassisted automated correcting
+- Fast, can quickly run across large code bases
 
 Dictionary: A confidence rating is given for how close a word is to one in a dictionary
 - Sensitive to false positives due to hex numbers and c-escapes
-- Traditional spell checkers use a dictionary.
-
+- Used in word processors and other traditional spell checking applications
+- Good when there is a UI to let the user know and override any decisions