When Drupal CMS 1.0 launched, we rushed to create an MVP of the Drupal CMS Guide. Now, we’re circling back to try and address some loose ends—how should this guide evolve, and how does it relate to the existing Drupal User Guide?
The Drupal CMS Guide, like Drupal CMS itself, was conceived and started super quickly. And guidance from others in the Starshot Initiative on what it should or shouldn’t include has been pretty minimal. So we’re making a lot of this up as we go.
We wanted to have something to show when Drupal CMS first launched. But, that meant plowing ahead on an MVP while leaving a lot of questions unanswered. Now, I’m both trying to push more content into the pipeline, while also circling back to spend more time thinking about some of these big picture questions.
A key question is how the Drupal CMS Guide relates to the existing Drupal User Guide. Defining this relationship will streamline future content decisions and development. Not to mention removing something that has proven to be a big mental blocker for me personally.
Background
I’ve been deeply involved in the creation and ongoing maintenance of both the Drupal User Guide and the Drupal CMS Guide.
The Drupal User Guide is a community-driven effort to provide a clear, structured introduction for Drupal site builders. It follows a style guide, stays up-to-date, is translatable, and uses Git for editorial workflows. Drupalize.Me has sponsored much of my work on it, and because the guide is licensed under CC BY-SA, we can also republish it on Drupalize.Me—benefiting both our site and the Drupal community by keeping it maintained.
To keep things manageable a decision was made early on when writing the User Guide to focus only on Drupal core—avoiding the complexity of deciding which contributed modules to include, and thus document.
The Drupal CMS Guide shares many of the same goals but takes a different approach. The whole idea is that Drupal CMS is built around core plus commonly used contributed modules and a better reflection of how Drupal is really used.
End user documentation for Drupal CMS shouldn’t differentiate between Drupal core, and contributed modules. Instead it should focus on the cohesive feature set created through the combination of these parts.
This creates a key challenge: While someone could learn Drupal -- including Drupal CMS -- from the User Guide, the UI, content structure, and site configuration workflows in Drupal CMS differ from Drupal core due to what's shipped with Drupal CMS. For example, Drupal CMS uses the Gin admin theme instead of Claro, meaning screenshots won’t always match. Readers can mentally adjust, but they shouldn’t have to—that’s unnecessary cognitive load.
Another example: Documenting how to create content in Drupal CMS means covering SEO metadata, automatic URL aliases, and other features added by contributed modules—things not included in the core-only Drupal User Guide.
Each guide serves slightly different audiences. The Drupal User Guide focuses on best practices for core Drupal, which assumes using Composer to install and manage dependencies. Meanwhile, Drupal CMS is designed to work entirely in the browser, making it more beginner-friendly.
Finally, with the Drupal User Guide already written, we should aim to reuse it as much as possible rather than reinvent the wheel.
Two guides? Or one mega guide?
One of my biggest questions right now is what is the relationship between these two chunks of documentation? Should they be combined, or kept separate? And why? This is similar to the broader question of how Drupal CMS and Drupal core relate to one another that a lot of people in the community and the Starshot leadership team are trying to work through right now.
| Drupal CMS Guide current working outline (Feb. 2025) | Drupal User Guide outline |
|---|---|
|
|
One of the things I want to dive back into now though is answering that question. And I still don’t have an answer, but here are some of the things that are on my mind as I’m thinking through this/
The Drupal CMS Guide is a work in progress. As of February 2025, this outline reflects our current thinking, shaped by Drupal CMS’s features, the needs of the Adopt a Document program, hints from the Starshot leadership team, and lots of brainstorming sessions between Amber and me. Some sections (those with a ✅) are done, while many others are still on our to-do list. And there are still key topics missing that should be included.
There’s already a lot of overlap between this and the Drupal User Guide. Comparing the two outlines side by side, as you can read above, it’s clear that the Drupal CMS Guide is missing essential site-building topics. Things like adding pages to navigation, modeling content types with the Field UI, and creating views. These skills are crucial for both Drupal CMS and core users.
So far, we’ve tried to avoid duplicating content from the User Guide by linking to it instead. But that quickly creates a frustrating experience by forcing users to jump between two guides with different screenshots and interfaces because of the contributed modules and recipes in Drupal CMS.
Early on, we considered merging the User Guide into the CMS Guide entirely. But that raised bigger questions:
- Who is the CMS Guide really for?
- How should it be managed?
- What’s the best way to handle content updates?
Without clear answers, we pushed forward without worrying too much about duplication—for now.
Now, it’s time to revisit that question. I still don’t have a final answer, but here are some of the key things on my mind as I think this through.
Maintenance
- We don’t want to write from scratch something that’s already been written for the User Guide. But I also don’t want to maintain two versions of nearly identical content.
- We’re planning to add a Git-based editorial workflow for the Drupal CMS Guide. The User Guide already has one. But they’re not going to be the same and the User Guide will need to get completely refactored regardless. See Decide on the future of the user guide [#3470837], which also contains some ongoing discussions about moving the User Guide away from asciidoc.
- As someone doing work to maintain both, I’m keenly aware of not wanting to add any extra work for myself or anyone else.
Scope
- Does the Drupal CMS Guide only document things that are specific to Drupal CMS? And defer to the Drupal User Guide for things that are part of both Drupal CMS and Drupal core? Like, for example, managing blocks. Presumably Drupal CMS users will want to manage blocks. Or create custom content types. Or Views.
- Drupal CMS includes a bunch of contributed modules, and their features. The current version of the User Guide’s policy is to document only things available in core.
- How does it impact the overall experience of the reader if they’re constantly jumping between two different guides for different things. They don’t know about the difference between Drupal CMS, and Drupal core, and they shouldn’t need to.
- What about the content in the User Guide that deals with things like installing Drupal using Composer, or updating modules & themes using Composer? These are probably still relevant to a lot of Drupal CMS users, but their exact mechanics vary. And, in theory, the Drupal CMS Guide's current goal is to not include giving instructions that require using the CLI. Or writing code.
- A lot of Drupal CMS's features are destined for core, including Project Browser, Automatic Updates, Recipes, Experience Builder, etc. So, do those get documented in the User Guide or the Drupal CMS Guide?
Audience
- Can we assume that Drupal CMS will be the starting point for most (all?) people who are new to Drupal? Should it be? It’s definitely a more holistic example of what building a real Drupal site feels like.
Translation
- All 120+ pages, and all screenshots, of the existing User Guide have been translated into 12 different languages. Creating, and maintaining, those translations also takes a lot of effort and is accomplished by just a few people so again what solution means the least amount of additional work with the greatest translation coverage?
Value
- From the Drupalize.Me perspective, we’ve got a lot of content, like our Module Developer Guide, that is a continuation of where the current User Guide leaves off. If the User Guide disappears because it becomes part of the Drupal CMS Guide that’s going to mean a lot of content updates and re-recording of videos for us.
What do I think?
I’m leaning towards combining them. We should merge the guides, prioritizing Drupal CMS as the primary experience for new users. Users who install only Drupal core can still follow along, with clear notes where differences exist.
I think that if there are two guides it’s confusing to someone who is trying to figure out where to start with Drupal. And we should be trying to remove these points where someone gets stuck trying to figure out which option they should choose.
But I don’t have a definitive answer yet. Part of writing this blog post is an exercise in trying to collect my thoughts. And to have them written down so I can share with others.
What do you think?
If you’ve got thoughts about what would help to make Drupal’s documentation best-in-class with regards to these two guides feel free to leave a comment, ping me in Slack, or track me down at DrupalCon Atlanta.
Add new comment