Should new Drupal User Guide videos use Drupal 11 or Drupal CMS?

Drupalize.Me is planning to re-record the video tutorials that accompany the task tutorials in the Drupal User Guide. These videos were originally created for Drupal 8, and it’s time for an update.

As part of this effort, we’re trying to decide whether to record the videos using Drupal 11 or Drupal CMS, and I'm interested to hear the communities thoughts on this before we get started.

Background

The original video series uses the now-(very)outdated Drupal 8 interface. In updating them, we want to align with the most relevant and accessible experience for new users. And for the target audience of the guide, current defined as:

This guide was written mainly for people with minimal knowledge of the Drupal content management system. The topics will help them become skilled at installing, administering, site building, and/or maintaining the content of a Drupal-based website.

. More: https://www.drupal.org/docs/user_guide/en/preface-audience.html

Also of note, the Drupal User Guide currently sticks to documenting only features of Drupal core. Drupal CMS includes numerous non-core modules. Which, for now we could sort of ignore since all the core features are still there.

While Drupal 11 and Drupal CMS are functionally similar, there is one key difference that affects video tutorials: they use different admin themes by default. Drupal 11 (core) currently defaults to the Claro admin theme. Drupal CMS uses the Gin admin theme and includes several modules and configuration choices intended to improve the experience for new site builders.

This distinction is important in video recordings since the admin UI will look different between the two options.

Proposal

We are leaning toward recording the new videos using Drupal CMS for the following reasons:

• We believe Drupal CMS will increasingly be the entry point for people new to Drupal.
• The User Guide is intended for beginners—people who are most likely to download Drupal CMS to get started.
• Drupal CMS offers a better out-of-the-box experience for new users (e.g., Gin theme, pre-installed contrib modules).
• Aligning with Drupal CMS reduces the gap between what users see in the videos and what they experience when following along.
• While there's a distinct Drupal CMS Guide right now having the content of this guide look like Drupal CMS will make it less confusing to link between these two guides and reduce the need for duplication.
• And, regarding the last point, we believe that users who watch a video that shows the Drupal CMS UI will be able to translate that to what they're seeing in Drupal core only sites.

If we record videos in Drupal CMS we would also update all the screenshots in the current guide. Which, I don't think will impact any of the translations in terms of the need to update text, but we would need to update all the images in the translations too.

My biggest concern right now would be that the Drupal CMS UI is likely to change a lot more rapidly than Drupal core, which would mean the videos will become out-of-date and need updating again sooner. Though I do also think there will continue to be some ability to expect people to be able to translate between what they're seeing in an older video and the most up-to-date UI.

Feedback

If you've got any input before we commit to this approach I'm would love to hear it:

• Do you agree that Drupal CMS is the right choice for this audience and these videos?
• Would using Drupal CMS in the videos create confusion for anyone using Drupal core directly?
• Should the User Guide or video intros include clarification about the differences between Drupal CMS and Drupal core?
• Any other concerns, suggestions?

Thanks in advance for sharing your thoughts!

Changes required

Based on updating all the screenshots, and reviewing all the instructions in the user guide against Drupal CMS here's a list of the changes that would be required to adapt the user guide to Drupal CMS.

📝 Intro and Installation

• [ ] Add tutorial explaining that we're using Drupal CMS but this also applies to Drupal core, and why
  • Include examples: drupal_cms_olivero vs. olivero, gin vs. claro
• [ ] Review and clarify install instructions
  • Decide whether to show Drupal CMS installer, Drupal core, or both
• [ ] In tutorials where we walk through enabling a module make sure to enable block_content since we'll need it later

📄 Content Creation and Types

• [ ] Update field creation steps to be consistent with Drupal CMS fields
  • Change "Body" to Content
  • Change "Summary" to Description
• [ ] Modify content creation and editing tutorials
  • Create an About page since Drupal CMS already has a home page.
  • Walk through editing the pre-existing /home page
• [ ] Review content type management section
  • Note: Article type not installed in Drupal CMS
    • Create a dummy content type in tutorial/tests to later delete
    • Add note: "This content type is added by Drupal core..."
  • Mention that as of 11.1, Body (Content) field is not added automatically
  • Add tutorial on re-using existing fields and then re-use the content and description fields from Drupal CMS.
  • Add “Content” and “Description” fields to Recipe and Vendor types
• [ ] Update text formats section
  • Drupal CMS names the text format Content, not Basic HTML

👤 User Accounts

• [ ] Update user creation process
  • Note: notify checkbox checked by default, password hidden, random pass + one-time login (via ECA)
  • Update language for Status (Active/Blocked) field
• [ ] Remove profile picture upload step
  • Drupal CMS does not include picture field
• [ ] Remove contact module references
  • Not enabled by default in Drupal CMS

🔐 Permissions & Settings

• [ ] Update permissions tutorial
  • Replace “Post comments” with Create and edit URL aliases comment module not enabled in Drupal CMS
  • Remove references to contact module settings - not enabled in Drupal CMS
• [ ] Replace text format name
  • “Restricted HTML” → Content

📦 Blocks

• [ ] Replace “Who’s online” block with Recent content when talking about placing a block
• [ ] Update custom block tutorials - Drupal CMS doesn't have block_content enabled by default ...
  • Ensure Block Content module is enabled in:
    • [ ] https://www.drupal.org/docs/user_guide/en/config-install.html
    • [ ] https://www.drupal.org/docs/user_guide/en/block-create-custom.html
  • Add a new tutorial that walks through creating a custom block type, so that we can then create a custom block, instructions:
    • Enable module (should have been done earlier)
    • Create Basic block content type:
      • ID: basic
      • Label: Basic block
      • Description: A basic block contains a title and a body.
    • Use “Save and configure” hidden action in Gin toolbar

🔍 Global Find & Replace

• [ ] Search for “Body” and replace appropriately with Content

🌐 New Strings for Translation

• [ ] Add translations for these new strings in the automatic screenshot tests:

<span class="hljs-symbol">'vendor_field_body_label'</span> =&gt; <span class="hljs-symbol">'Content'</span>,
<span class="hljs-symbol">'vendor_field_body_machine_name'</span> =&gt; <span class="hljs-symbol">'content'</span>,
<span class="hljs-symbol">'recipe_field_body_label'</span> =&gt; <span class="hljs-symbol">'Body'</span>,
<span class="hljs-symbol">'recipe_field_body_machine_name'</span> =&gt; <span class="hljs-symbol">'body'</span>,
<span class="hljs-symbol">'block_type_machine_name'</span> =&gt; <span class="hljs-symbol">'basic'</span>,
<span class="hljs-symbol">'block_type_label'</span> =&gt; <span class="hljs-symbol">'Basic</span> block',
<span class="hljs-symbol">'block_type_description'</span> =&gt; <span class="hljs-symbol">'A</span> basic block contains a title <span class="hljs-keyword">and</span> a body.<span class="hljs-string">',</span>