diff --git a/README.md b/README.md
index 51319e2..8f6233c 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,7 @@
 - 🛠️ No need to manually compile plugins
 - 🧪 Correct sequencing of dependencies
 - 📁 Configurable in multiple files
+- 📚 Generates helptags of the headings in `README.md` files for plugins that don't have vimdocs
 - 💻 Dev options and patterns for using local plugins
 - 📊 Profiling tools to optimize performance
 - 🔒 Lockfile `lazy-lock.json` to keep track of installed plugins
diff --git a/lua/lazy/core/config.lua b/lua/lazy/core/config.lua
index 522bf64..4190c10 100644
--- a/lua/lazy/core/config.lua
+++ b/lua/lazy/core/config.lua
@@ -75,9 +75,13 @@ M.defaults = {
       },
     },
   },
+  -- lazy can generate helptags from the headings in markdown readme files,
+  -- so :help works even for plugins that don't have vim docs.
+  -- when the readme opens with :help it will be correctly displayed as markdown
   readme = {
     root = vim.fn.stdpath("state") .. "/lazy/readme",
     files = { "README.md" },
+    -- only generate markdown helptags for plugins that dont have docs
     skip_if_doc_exists = true,
   },
   debug = false,