diff --git a/README.md b/README.md
index 3e71bc7d6..1b19ee06b 100644
--- a/README.md
+++ b/README.md
@@ -10,10 +10,54 @@ data (lisps, JSON), it works sometimes on other languages with
 sufficient parentheses (Rust, JS), and falls back to a line-oriented
 diff otherwise.
 
-See `config/syntax.toml` to see how languages are defined.
+## How It Works
 
-The [wiki](https://github.com/Wilfred/difftastic/wiki) includes a
-thorough overview of alternative diffing techniques and tools.
+(1) Parsing.
+
+Difftastic treats source code as a sequence of atoms or (possibly
+nested) lists.
+
+Language syntax is defined in `config/syntax.toml`: you provide
+regular expressions for atoms (including comments), open delimiters,
+and close delimiters.
+
+This is heavily inspired by
+[Comby](https://github.com/comby-tools/comby), which handles a large
+number of languages by using a similar approach.
+
+(2) Diffing.
+
+Difftastic treats diff calculations as a graph search problem. It
+finds the minimal diff using Dijkstra's algorithm.
+
+This is based on the excellent
+[Autochrome](https://fazzone.github.io/autochrome.html) project.
+
+(3) Printing.
+
+Difftastic prints a side-by-side diff that fits the current
+terminal. It will try to align unchanged nodes (see screenshot above).
+
+## Known Problems
+
+Crashes. The code is underdocumented, undertested, and unfinished.
+
+Performance. Difftastic scales poorly on files with a large number of
+changes. This might be solved by A* search.
+
+[Sliders](https://twitter.com/_wilfredh/status/1411949035871637509).
+
+Replacing top-level expressions. If you delete a function and write a
+completely different new one, difftastic will show the small number of
+common tokens between them.
+
+Comments. Small changes can show big diffs.
+
+## Non-goals
+
+Patch files. If you want to create a patch that you can later apply,
+use `diff`. Difftastic ignores whitespace, so it is output is
+lossy. (AST patching is also a hard problem.)
 
 ## Testing with Git
 
@@ -27,3 +71,8 @@ thorough overview of alternative diffing techniques and tools.
 
 You can then run `git difftool -y` to see the current repo changes in
 difftastic.
+
+## Further Reading
+
+The [wiki](https://github.com/Wilfred/difftastic/wiki) includes a
+thorough overview of alternative diffing techniques and tools.