diff --git a/README.md b/README.md
index 74da116ec93d1b8a00b0b51068687eb779b5b568..0fa61180fd76091590db61b438424ab75e020d3d 100644
--- a/README.md
+++ b/README.md
@@ -136,6 +136,8 @@ In this directory you will find
 - `datadir` Once your sbws scanner has started gathering results, it will dump
   them into this directory. Other sbws commands (such as generate and stats)
   read results from the files in this directory.
+- `state.dat` A file for storing state needed between sbws commands. See its
+  documentation for more information.
 
 ## Running tests
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 43eb373b929471639a2bf6e482440305db6dd39f..7f3a993752c9782b557d551f33e9656476845890 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -25,6 +25,7 @@ Contents
    faq
    glossary
    diagrams
+   state
    sbws
 
 Proposals
diff --git a/docs/source/sbws.util.rst b/docs/source/sbws.util.rst
index dd62d260f971bf37ea2b93d84a83f53ab98c732b..a1b384058ebee0fab15c3833d9bb5f66fa3b995d 100644
--- a/docs/source/sbws.util.rst
+++ b/docs/source/sbws.util.rst
@@ -28,6 +28,14 @@ sbws.util.parser module
     :undoc-members:
     :show-inheritance:
 
+sbws.util.state module
+~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: sbws.util.state
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 sbws.util.stem module
 ~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/source/state.rst b/docs/source/state.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b61b69e8d489e30743bc2bc8cf98c998d56bf748
--- /dev/null
+++ b/docs/source/state.rst
@@ -0,0 +1,20 @@
+The ``state.dat`` file
+======================
+
+This file contains state that multiple sbws commands may want access to and
+that needs to persist across processes. Both read and write access to this file
+is wrapped in the ``State`` class, allowing for safe concurrent access: the
+file is locked before reading or writing, and (for now) only simple data types
+are allowed so we can be sure to update the state file on disk every time the
+state is modified in memory.
+
+At the time of writing, the following fields can exist in the state file.
+
+``scanner_started``
+-------------------
+
+The last time ``sbws scanner`` was started.
+
+- **Producer**: ``sbws scanner``, once at startup.
+
+- **Consumer**: ``sbws generate``, once each time it is ran.