diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 00000000..1599a32e
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,30 @@
+# Conky docs
+
+There are 3 YAML files which contain the documentation:
+
+* [`variables.yaml`](variables.yaml): Documents each object/variable
+* [`config_settings.yaml`](config_settings.yaml): Documents global configuration settings
+* [`lua.yaml`](lua.yaml): Documents Conky's Lua API
+
+The `desc` field within the docs can be formatted with markdown, however _do
+not_ include headings within the `desc` fields, as it will mess up the man page
+output. In markdown, headings begin with `#`.
+
+## Updating docs
+
+The man page is based on [`man.md.j2`](man.md.j2) which is a Jinja2 template.
+The generated markdown is used to generate a final man page using
+[`pandoc`](https://pandoc.org/). Generating the final man page is a 2 step
+process:
+
+1. Run `docgen.py` to process `man.md.j2`:
+   ```console
+   $ ./docgen.py man.md.j2 > man.md
+   ```
+2. Run `pandoc` to convert the markdown into a man page:
+   ```console
+   $ pandoc -f markdown -t man.md > conky.1
+   ```
+
+These steps are also part of the CMake build, and can be executed by configuring
+the build with `-DBUILD_DOCS=ON`.
diff --git a/doc/config_settings.yaml b/doc/config_settings.yaml
index 4f907213..1c21f200 100644
--- a/doc/config_settings.yaml
+++ b/doc/config_settings.yaml
@@ -1,3 +1,7 @@
+# See README.md for details on doc processing.
+#
+# The `desc` field can be formatted with markdown, but please do not include
+# headings (lines beginning with `#`) in the `desc` field.
 ---
 - name: alignment
   desc: |-
diff --git a/doc/lua.yaml b/doc/lua.yaml
index c53d4c56..4e0113a7 100644
--- a/doc/lua.yaml
+++ b/doc/lua.yaml
@@ -1,3 +1,7 @@
+# See README.md for details on doc processing.
+#
+# The `desc` field can be formatted with markdown, but please do not include
+# headings (lines beginning with `#`) in the `desc` field.
 ---
 - name: cairo_font_extents_t:create()
   desc: |-
diff --git a/doc/variables.yaml b/doc/variables.yaml
index e9a2dd82..9ff5dc87 100644
--- a/doc/variables.yaml
+++ b/doc/variables.yaml
@@ -1,3 +1,7 @@
+# See README.md for details on doc processing.
+#
+# The `desc` field can be formatted with markdown, but please do not include
+# headings (lines beginning with `#`) in the `desc` field.
 ---
 - name: acpiacadapter
   desc: |-