There are 2 big changes in Drupal 10 that have a huge impact on documentation: the new default public-facing theme, Olivero, and the new administrator-facing theme, Claro. They're both beautiful, modern—and deliver a much needed update. The introduction of these new default themes means that a whole lot of screenshots and video are now out-of-date.
It can be frustrating when the images in the documentation don't match what you're seeing on your own project. It can diminish your confidence in the quality of the documentation (even if the surrounding text is technically correct).
A quick aside: These themes primarilly change the way things look or where components are placed on the page but rarely change what words are on the page or what happens when you click a button. So, things like videos will often still contain accurate steps to perform the task even if the UI looks different. You’re still clicking a button called “Save” even if it’s a different shape or color.
For example, here’s a side-by-side comparison of the node creation form in Seven vs. Claro themes:
When the Drupal User Guide was originally written, we predicted that something like this might happen in the future and planned for it. Jennifer wrote a set of FunctionalJavascript tests that make use of Drupal core's own testing infrastructure. These tests walk through all the tasks outlined in the content of the User Guide and generate screenshots along the way. This reduces the burden of updating screenshots since the majority of them are automated.
Given that the screenshots also need to be maintained for all the different translations of the guide, the number of generated screenshots easily numbers around 2,000 images.
Having these automated tests also has the benefit of pointing out any places where steps in the documentation might change in a new release. For example, the Drupal 9 documentation tells you to enable the Color module, and then navigate to the configuration page for your theme to modify the colors. The Color module was removed in Drupal 10; and the color settings—while still available—are quite different between Bartik (the previous default theme) and Olivero (the new default theme).
From a technical perspective, these tests use PHPUnit + Selenium + Chrome to simulate all the clicks and keyboard interactions someone would go through if they followed the User Guide step-by-step. Along the way, it uses some JavaScript to show/hide/highlight things on the page and make a screenshot of the results of that interaction.
You can find the code here if you're curious. Running the tests requires some special environment setup; so, I've also got a DDEV-based environment I use for development here.
Generating updated screenshots for Drupal 10
As of right now, generating the new screenshots and updating the text for Drupal 10 is still a work in progress. But it's really close. You can track progress here if you're curious about its status.
In order to generate new screenshots for Drupal 10 I had to do a couple of things:
- Update the code in the user_guide_tests project for Drupal 10. This work involved converting deprecated test methods to their new versions. I was able to automate a lot of this using Upgrade Status. And the rest required a day or so of reading change records and doing manual updates. It's a LOT of code. Mostly simple. But a lot.
- Run the English language tests. Wait for them to fail. Fix the failures.
The test failures came in a few common forms:
- UI text changes. For example, Drupal 9's empty front page said "No frontpage content created yet." and Drupal 10's says "You haven’t created any frontpage content yet.". CKEditor 5 refers to the
<hr>as a "Horizontal line" while CKEditor 4 called it a "Horizontal rule". - Feature changes. For example, Olivero only has a single sidebar region while Bartik had 2. And Bartik displayed the site slogan in the header by default (if it was set) and Olivero does not.
- Feature removal. For example, The Quick Edit module was removed from Drupal 10.
For each issue I found I had to update the tests. I used that to create a to-do list for updates that needed to be made to the text of the User Guide. Given that the tests (just the English ones) take about 15 minutes to run, this was a somewhat tedious process.
Finally, I had to update all the translation .po files, and run the tests for each individual language. I posted a video of what that looks like here. This surfaced a few more minor bugs, mostly related to things like the German translation for Drupal core having an extra white space in the translation from "Create a Label" to "Beschriftung erstellen".
As an example, here’s a side-by-side comparison of a view listing recipes rendered in Bartik vs. Olivero themes:
But the tests are passing again and we should be able to deploy a version of the Drupal User Guide with updated screenshots to Drupal.org soon.
The next steps are:
- Review the new screenshots
- Review and copy edit the updates to the text of the guide. (Amber completed this review while I was writing this blog post. Thanks, Amber!)
- Once this is done we'll deploy an update to the English version on Drupal.org, and on Drupalize.Me where we currently publish the English version only.
- Notify translation teams about the text changes and the removal of a page about the Quick Edit module, so they can update their source files.
- Ship it!
Oh yeah...and update the videos
Yeah...I, too, wish we had a way to automate the updates to all the videos embedded in the User Guide. Alas, we don't yet and doing so requires many hours of re-recording and editing. It's on our to-do list but we figured we would deal with the screenshots and text updates first.
Add new comment