diff --git a/docs/codelist-updating.md b/docs/codelist-updating.md
new file mode 100644
index 000000000..edb8763c8
--- /dev/null
+++ b/docs/codelist-updating.md
@@ -0,0 +1,48 @@
+Once your codelists are [imported into your study](codelist-project.md), they are ready to be
+used for running jobs on the [jobs site](jobs-site.md).
+
+You may encounter a warning message when you try to run jobs, that looks something like this:
+
+![Out of date codelists warning on Jobs site.](images/codelists-jobs-warning.png)
+
+
+To fix this, you will need to follow the steps to [add a codelist into your study](codelist-project.md#adding-updating-a-codelist-CSV-file) again.
+
+Note that this warning is only relevant if the jobs you are running require access to the
+backend database. Analysis jobs that use data that has already been extracted in a previous
+run do not need to update codelists in order to run successfully.
+
+
+## What are "out-of-date" codelists?
+
+Codelists may sometimes go "out-of-date".  All coding systems change (with the exception of CTv3, which is no longer updated), and new releases are published which may add new codes or retire codes.
+
+A codelist version on OpenCodelists is associated with a specific release of a coding system,
+and once under review or published, it cannot change. This means that, for the most part, any
+codelist that has been specified in `codelists.txt` with a `version-id` and downloaded into
+a study repo will not need to be updated again.
+
+!!! warning
+
+    This does not mean that the codelist is up-to-date with the most recent release of a coding
+    system. It only means that the version downloaded in the study has not changed on
+    OpenCodelists.
+
+You may need to create new versions of codelists in order to update them to a more recent
+coding system release. To do this, go to an existing Codelist page and click on Create new
+version.
+
+### dm+d: a special case
+
+Codelists created with the Dictionary of Medicines and Devices (dm+d) coding system are special cases. The dm+d coding coding system is updated and released on a weekly basis. Codes for Virtual Medicinal Products (VMPs) can change, and are retrospectively updated in patients’
+clinical records. This means that after a new release of dm+d, a VMP with a changed code will no longer match patients that it did previously.
+
+In order to address this, OpenCodelists maintains a mapping of changed VMP codes. When you run
+`opensafely codelists update` to download codelist CSV files into your study repo, dm+d
+codelist CSV files will include the codes explicitly specified in the codelist *and* any
+previous or subsequent changes to those codes.
+
+If a new release of dm+d introduces new VMP mappings that affect codes in your codelists, you
+,ay be prompted (by the opensafely command line tool, automated tests in GitHUb, or the jobs site) to re-run
+`opensafely codelists update`, commit the changes and push them to GitHub before you can run
+jobs.
diff --git a/docs/images/codelists-jobs-warning.png b/docs/images/codelists-jobs-warning.png
new file mode 100644
index 000000000..f8d27615e
Binary files /dev/null and b/docs/images/codelists-jobs-warning.png differ
diff --git a/mkdocs.yml b/mkdocs.yml
index fbbb1a374..2e807e10b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -38,6 +38,7 @@ nav:
           - Introduction to codelists: codelist-intro.md
           - Building a codelist: codelist-creation.md
           - Adding codelists to a project: codelist-project.md
+          - Keeping codelists up to date: codelist-updating.md
       - Actions:
           - Overview: actions-intro.md
           - The project pipeline: actions-pipelines.md