Drupal 11 was released recently. Yay 🎉. And with it comes a bunch of minor (and sometimes major) changes to the way Drupal works and the need to update the documentation to reflect those changes.
Since we first helped coordinate its creation, we’ve been committed to helping keep the Drupal User Guide content on Drupal.org (and mirrored on our site) up-to-date – and free. Part of this work is updating the content of the guide as Drupal evolves, so that it always reflects the latest major stable release. This includes figuring out what changed, drafting an update, technical review of the updates, and copy editing. It really is a team effort.
Drupal 11 updates for the User Guide
Here’s some of the things that needed to be addressed for the Drupal 11 version of the guide:
-
New UX for adding fields to an entity type – The “Add a field” form workflow, including where and what information is collected has changed.
-
Actions UI module removed from core – We had used Actions UI module in the instructions for installing and uninstalling a module. So, we updated those steps to use the Ban module instead.
Change record
-
Using Composer to download Drupal core and contributed modules and themes is an established standard practice – While it’s still technically possible to install Drupal and various modules from a .tar.gz file downloaded from Drupal.org, it has long been recommended (and in many cases required) to use Composer. We’ve chosen to remove content from the guide that relates to installing modules and themes via any means other than Composer. This helps simplify the guide, and reduces some of the decision fatigue users may experience when trying to learn Drupal from this guide.
-
Update Manager UI removed module installation – Related to the above, Drupal 10.4 and Drupal 11 removed the ability to install a module via the Update Manager UI. You used to be able to copy/paste the URL of a .tar.gz file from Drupal.org and install it. The User Guide previously relied heavily on this feature, but we rewrote these steps to use Composer. A UI for module installation would be preferred, of course – especially for newcomers. We’ll revisit these parts of the guide once Project Browser and Automatic Updates core modules are stable and widely used.
Related issue
-
Updated screenshots for everything – More about that process below.
-
Updated system requirements for PHP and MySQL/MariaDB – We updated the system requirements for PHP and MySQL/MariaDB, and removed Microsoft IIS info.
Screenshot updates
Updating the User Guide content also means running the automatic screenshot generation scripts – which pretty much always require a bit of tweaking, too. And while this is usually not difficult to do, it’s often quite tedious. The screenshots are generated by a set of Drupal FunctionalJavaScript tests that essentially walk through the same steps as the guide taking screenshots along the way. These tests take a solid 10 minutes to run on my laptop, so the whole process of running the test, inspecting the debug output, tweaking the test, and running it again adds up to a big chunk of time. But once the scripts are working, I can generate all the screenshots, for all translations, pretty quickly.
This time around I had to make some updates to remove references to the Actions UI module. And I revised the screenshots generated for the tutorials on installing and updating themes and modules, since the use of the Update Manager UI is no longer mentioned in the content. I also did a bunch of work to ensure the screenshot generation works via GitLabCI pipelines.
Future updates
-
Rewrite server/environment-related content to recommend the use of DDEV.
-
Update content related to installing a module or theme to recommend Project Browser and Automatic Updates UI modules when those are stable and widely recommended.
-
Add content about using Layout Builder/Experience Builder.
-
Figure out how the Drupal User Guide might relate to the work on the Drupal Starshot initiative, aka the future “Drupal CMS” release. For example, adding content things like Recipes, Experience Builder, and the practice of including non-core modules in an official release.
The videos need to be re-recorded
The videos for the task tutorials in the guide are all in need of an update. We’ve updated a few here and there since they were first recorded, but they’re all dated now and need updating. With the inclusion of Claro and Olivero in Drupal 10, the videos no longer match what a user sees on screen. For Drupal 10, this was tolerable because the videos were still technically accurate. The names of buttons, and location of elements on the page didn’t change. But their appearance did. In Drupal 11 with things like the updates to the Field UI, and many other UX improvements, it’s time for them to be re-done.
Re-recording the videos is a big task. We generally estimate about 1 hour of work for 1 minute of final production quality video. The guide has 53 videos, and if we say they’re each 4 minutes or less that’s a little more than 200 hours of work. We don’t yet have a timeline for this work, but it’s on our radar.
Your Drupalize.Me membership supports this content
At Drupalize.Me, we know from experience that keeping documentation up-to-date and accurate is a time-consuming and often arduous process. And this is even more of an issue with documentation (like that on Drupal.org) that relies on a community of volunteers to maintain it. We’re committed to helping keep the Drupal User Guide content on Drupal.org (and mirrored on our site) up-to-date and free. When you pay for a Drupalize.Me membership, you’re helping make this possible. So, thank-you to our members – past, present, and future.
Add new comment