Hello everyone,
I often work with Drupal‑based sites and have noticed that documentation contributions tend to lag behind code updates—especially when modules evolve fast. I wanted to open a discussion on how we might streamline this process.
A few observations:
-
When a module adds a new hook or service, the docs update sometimes happens after community adoption spreads. This leads to confusion for newcomers.
-
Our contribution workflows often focus on code reviews; documentation usually isn’t part of the mandatory review checklist.
-
Documentation formatting (e.g., Markdown vs Drupal’s own markup) and placement (within module folder vs separate docs repo) vary widely across projects.
Questions for the community:
-
How do you enforce documentation updates when releasing new versions of a module?
-
Do you favour one method/version control strategy (e.g., docs living alongside code vs separate repo)?
-
What tools or workflows have you adopted to automate or alert documentation gaps when code changes significantly?
Would love to hear about experiences, best practices, or even workflows/tools you’ve found helpful.
Thanks,
James
