diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 5f210be..da4170b 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -7,7 +7,8 @@
     - [Advanced](advanced.md)
     - [TUI](tui.md)
 - [Contributing](contributing.md)
+    - [Documentation](documentation.md)
+    - [Release procedure](release.md)
 - [Changelog](changelog.md)
-- [Release procedure](release.md)
 
 [License](license.md)
diff --git a/docs/documentation.md b/docs/documentation.md
new file mode 100644
index 0000000..62c2282
--- /dev/null
+++ b/docs/documentation.md
@@ -0,0 +1,38 @@
+Documentation
+=============
+
+Documentation is generated using [mdBook](https://rust-lang.github.io/mdBook/).
+
+Documentation is written in markdown and located in the `docs` directory.
+
+Additional plugins:
+
+- [mdbook-toc](https://github.com/badboy/mdbook-toc)
+
+Install prerequisites
+---------------------
+
+You'll need a moderately recent version of Rust (1.60) at the time of writing.
+Check out [mdbook installation docs](https://rust-lang.github.io/mdBook/guide/installation.html)
+for details.
+
+Install by building from source:
+
+```
+cargo install mdbook mdbook-toc
+```
+
+Generate
+--------
+
+HTML documentation is generated from sources by running:
+
+```
+mdbook build
+```
+
+To run a local server which will rebuild on change:
+
+```
+mdbook serve
+```
diff --git a/docs/release.md b/docs/release.md
index 604ef13..6d2dd4d 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -32,3 +32,12 @@ GitHub release
     * wheel distribution (.whl)
 
 TODO: this can be automated: https://developer.github.com/v3/repos/releases/
+
+Update documentation
+--------------------
+
+To regenerate HTML docs and deploy to toot.bezdomni.net:
+
+```
+make docs-deploy
+```