Locate drupalisms that might create confusion among users

Today we discuss this issue for 15 minutes at the weekly community UX meeting. The hope is to continue to discuss it at future meetings as well as to socialize the issue and solicit more feedback from a variety of users (potential as well as different roles/skill levels).

It's important to note that this issue is not focused/intended to result in "altering or changing" any language. Its goal is to build/collect a list of terms that have anecdotally been referred to during casual conversation while working on Drupal issues/sites in the past.

Anyone who has terms to suggest should please feel free to leave comments including those terms. We'll collect them and work to share them with the broader community and use them in the context of the Admin Menu organization.

Some words we identified during the toolbar card sort review that are drupalisms

• Content type vs authoring form vs template
• Node
• Structure (in the admin menu)
• Extend (in the admin menu)
• Blocks
• Module
• Views
• Taxonomy and taxonomy terms

A few more:

• Entity
• Micro-content
• Paragraphs
• Layout/layout builder

Some of these are not terms that an editor would encounter often, but could be better-defined when they do pop up.

Within the admin UI, when relating to lists of things, the word "weight" was confusing to me. The word "order" made more sense, but wanted to post that here to add it in the mix. Thank you!

Can't claim to be a new user, but things that still catch me out or are jarring:

1. People - it's a level of indirection to users/accounts, and it also contains the config for roles/permissions (which aren't people, or users, or accounts), see #2695771: Re-organise user/account items under admin/ → for more.

2. admin/config vs admin/structure.

Config is supposed to be for 'settings' and structure is supposed to be for 'structuring/building', but why are user fields under config when e.g. media fields are under structure? Similarly text formats, image styles, responsive images all feel like 'structure' but are also under config. This is partly a general IA issue but also I think config vs. structure is a terminological problem in itself.

3. 'Extend', I think d7ux added this and it was supposed to be a call to action, but 'Extensions' would be more standard. Except even that isn't really true because themes are extensions and they're in appearance. And it used to be admin/build/modules but it has the install profile listed so it's not really just modules either, although profiles are modules so it kind of is. There's also recipes and project browser coming up to deal with too.

Also want to register a minor protest at calling 'taxonomy' a 'Drupalism' - it very accurately describes what it is, to the point that (to our amazement) it tested really well at the 2008 usability testing (unlike menus and blocks and... literally everything else), with the one disclaimer that some of the people we did testing with were university library staff. It's also a high-level concept in Wordpress (wonder where they got that idea from :P) https://developer.wordpress.org/themes/basics/categories-tags-custom-tax...

Almost every part of what @catch mentioned here was in my almost ready written comment. Which I now can trash. Thanks @catch :-)

Only: Extend isn't that bad. And it is short, what is preferable in mobile menus. But yeah, I never understood why we need other names for pages which have simply only one thing in it? Why do not calling it exactly after the things on page? Why not simply "Modules"? Why not simply "Themes" instead of Appearance? That' what it is. And it would lower the confusion @catch explained in combination with other "extensions" or things which "extend". But yeah, that's maybe not a "Drupalism" but rather a UI/UX issue to discuss elsewhere.

Taxonomy/Terms are perfectly fine for me and the reason for that Wordpress uses these terminology could probably be caused by the fact that Matt → used to be one of the very early Drupal users and contributors before he left and "maid his own thaaang" ;-).

In addition to catch's #1 point, the distinction between people, roles, users, permissions can get very foggy very quickly, especially because USERS are people who are authorized to login and *use* the system, whereas a "person" could be something like a staff content type node, where they have a Staff Listing, or something like that, but may not have an equivalent User privilege. Also, for Roles, something to the distinction that a user can occupy several different roles, so how does that impact their permissions? ie, if the user is a WRITER (can CREATE articles) and also a PUBLISHER (can PUBLISH and DELETE articles), then what are they actually allowed to do?

We discussed this issue at the Drupal Usability Meeting 2023-09-15 📌 Drupal Usability Meeting 2023-09-15 Fixed .

Housekeeping:

1. Deadline for collecting general opinions and suggestions on this topic will be through October 31st, 2023.
2. Temporary spreadsheet for aggregating comments and external discussions can be found here: Google Sheet - Temp
3. Governance of this temporary document will be performed by several community members who are actively participating in the weekly Drupal Usability Meetings. (They will edit and update the document as needed).
4. We plan to hold a Birds of a Feather session at Drupal Con Lille 2023 and encourage anyone interested in attending the con to please consider sharing their opinions at this session.

It is important to note that we are attempting to manage scope on this issue. We are primarily focused on Drupalisms as they pertain to the Card Sorting exercise performed in relation to the Admin Menu. During the opinion gathering phase of this issue we may add any reasonable suggestions to the spreadsheet for consideration; however, our focus will continue to be on the Admin Menu.

We do not expect to have any direct recommendations on changes to core. Instead, this information may be a good starting place for future discussions intended to see more specific action in that domain.

Thank you everyone for your comments thus far! Please keep them coming.

One other detail from todays usability meeting, there was a consensus to add a second spreadsheet, the one about the h1 and page titles to the issue summary as well since it provides a slightly different angle. and benji noticed that the link to the comparison spreadsheet points to the slack thread. having the direct google sheets link might be preferable for anyone interested, that way there is no need to search in the thread. i am updating the issue summary accordingly.

Aaron McHale and Emma Horrell are running a BoF to address this issue at DrupalCon Lille:
https://events.drupal.org/lille2023/session/lets-work-together-uncover-a...

A few more words to add to the list:

Token
users will run into that concept as soon as the token module is added providing an interface to browse the available ones

The hierarchy of terms on here https://www.drupal.org/docs/drupal-apis/entity-api/bundles →
many of the terms are already mentioned but the page illustrates the entire complexity and levels of granularity well plus it contains a few more you not necessarily run into in the admin ui (bundles or sub-types) but you will in your daily interaction and conversations.

Most (all?) of the comments so far have addressed words that are used in the Drupal interface, which of course is reasonable and necessary. I would like to add a few words that are commonly used in Drupal culture, and which are so pervasive that I think they really mess us up.

I'll dive right into it.

• Developer. The rest of the world calls people who are able to start with an uninitialized web hosting account and leave a working production-ready website in its place "Web Developers" -- but for some reason in Drupal we call them (often derisively) "Site Builders."

The world "Developer" in Drupal is reserved for PHP coders who are adept at creating modules. While this is an important and useful skill, it shouldn't be the only definition of "developer" we acknowledge. This might sound like minor and persnickety complaint, I actually think this is one of the primary causes of the infamous "Drupal Cliff" -- it explains why projects have so much trouble finding Drupal people for their projects. They're looking for the wrong people! Most project need a master Site Builder full-time, with access to module development skills if needed -- but they advertise for "Drupal Developer" and end up with expensive coding resources who create custom modules for functions that are easily handled in Views.

• Themer. The rest of the world calls them "Front End Developers" and we should just use that terminology.
• Site Builder. We need to stop acting as if they're some sort of beginner-level developer. Drupal allows for the creation of very sophisticated and capable information architectures within its interface, this is a real and important skill.

A fully-fleshed out Drupal team typically includes not just module developer and FEDS, but "site builders", Dev-ops/sysadmins, content editors, graphic artists, and important consultants like Accessibility and security experts. Only a small portion of these very capable professional need to have the Drupal API memorized; they rest do different things.

Meeting held 08/01/2024 @emma-horrell @AaronMcHale @rkoller @drupalviking @cellear @worldlinemine @ckrina. Notes here:

https://docs.google.com/document/d/13Isn8_BdQK-Ze-A5G5JVTV7GP5b-IpoFXo3f-b-uN70/edit

Summary: (detailed in notes)
- Reviewed information we currently have about drupalisms
- Discussed some of the issues with Drupal terminology
- Considered the criteria that make terms drupalisms
- Began reviewing some of the drupalisms identified to consider alternative terms and ways to describe them

Next steps: Meeting scheduled 22/01/2024 to:
- Review more drupalisms
- Consider how we prioritise which drupalisms are the priority to address (test with novice users? frequency of use? prioritise those that differ from 'industry standard')?
- Discuss pros and cons of changing terms
- Discuss how we could describe them and associated feasibility - use of the glossary? embed descriptions in interface or within documentation?
- Discuss sustainability of solutions based on projected future terminology changes in Drupal

I found a bunch of related issues. I suspect they can be closed but leaving that for the folks here who are planning this work.

• #1991438: Terminology confusion: 'settings' vs. $configuration →
• #2513398: Conduct a full-scale terminology review of Drupal (Fix Drupal terminology so that it is more accessible to users) →
• 🐛 Settings vs. Configure for UI text? Active
• 📌 Word Manage at beginning of multiple admin page names make them hard to distinguish. Needs review

Meeting held 22/01/2024 @emma-horrell @rkoller @cellear @worldlinemine Notes here:

Drupalisms meeting progress log

Summary: (detailed in notes)
- @worldlinemine helped us define the scope of this issue and define the short term, long term and overarching goals
- We identified where we would like to get to: a controlled vocabulary for all versions of Drupal and a way for Drupal users to be able to understand what terms mean in context - for example in documentation and in the UI, in the language they speak. A process for new terms to be added and out-of-date terms to be removed to avoid confusion
- We identified key next steps: to make an inventory of drupalisms, define these in plainer terms and prioritise drupalisms to change based on evidence
- @rkoller made suggestions of how we may approach the development of a controlled vocabulary drawing on the work of Abby Covert and Erica Jorgensen.

Next steps: @rkoller to draft stages to work through towards a controlled vocabulary for all to review and feedback

Next meeting scheduled Monday 5 February 16:30-17:30 GMT

Meeting held 5/02/2024. @emmahorrell @rkoller @worldlinemine Notes here:

Drupalisms meeting progress log

Summary (detailed in notes):

• @rkoller took us through 6 stage process towards a Controlled Vocabulary

1. Draft terms
2. Evaluate terms based on how challenging they are, how frequently used, etc
3. From Evaluation, decide what to include in the Controlled Vocabulary
4. Work on multilingual Controlled Vocabularies
5. Make a list of ‘words we do not say’
6. Keep it alive with governance

All agreed on the approach, starting first stage of the process with ‘noun foraging’ - gathering nouns we encounter with Drupal (not only on Drupal.org but also in Slack, in forums, social media etc)

Plan to do usability testing with novice Drupal users to test which UI terms make sense/are confusing in the context of performing common tasks. First step: come up with a list of representative tasks to use in a test.

Discussion about how to get wider buy-in for this issue in the community. Ideas included taking to UX group at appropriate stage in the process.

Next meeting scheduled Monday 19 February 16:30 - 17:30 GMT

Meeting held 5/02/2024. @emmahorrell @rkoller @worldlinemine @AaronMcHale Notes here:

Drupalisms meeting progress log

Summary (full description and actions detailed in notes):

Idea to use data gathered from forthcoming navigation usability tests to help us understand how people make sense of UI Drupal terms in the context of tasks

Focused on actions we could take to build momentum around this issue and gain support/buy in from the community in the run up to DrupalCon Portland

Meeting held 04/03/2024 @emmahorrell @rkoller @AaronMcHale
Notes here:

Drupalisms meeting progress log

Summary (full description and actions detailed in notes):

Idea to run a top tasks style survey (using Drupal social media channels to promote) in the weeks leading up to DrupalCon Portland (May 6-9) to ask the community to vote on the Drupalisms they feel cause most confusion amongst people new to Drupal. The results of this survey would guide a BoF on Drupalisms - for example the BoF could involve attendees writing definitions for the top 10 terms emerging from the survey responses.

Actions: prepare for the survey: identify Drupalisms to include (no more than 100) and draft the survey introduction and question

Results of the survey and data gathered from the BoF could be used to guide developing this issue into an initiative.

Next meeting scheduled for Monday 18 March 16:30-17:30 GMT

Meeting held 18/03/2024 @emmahorrell @rkoller @worldlinemine @AaronMcHale
Notes here:

Drupalisms meeting progress log

Summary (full description and actions detailed in notes):

Further discussed the idea of a survey to gather data about the priority Drupalisms (the terms that cause most confusion). Survey is a good way to raise awareness, however, it may only reach people who know Drupal, and to address this issue we want to capture perspectives of those who are unfamiliar with Drupal and find some of the terminology confusing.

Actions: All to review survey draft and feed in thoughts/suggestions. Ask for Drupal Association's help in circulating/publicising the survey on social media, and investigate how we can publicise work on this issue at DrupalCon Portland

Next meeting scheduled for Monday 1 April 16:30-17:30 GMT

Short meeting held Monday 1 April 16:30 BST - followed up by an additional meeting on Monday 15 April 16:30 BST. Attended by @emmahorrell and @rkoller
Notes here:
Drupalisms meeting progress log

Summary:
Started examining up-to-date admin UI to ensure we have a complete list of terms

Identified that promoting this issue at DrupalCon Portland through a quiz or a top-tasks-style survey may not be possible given the short time we have left and the limited resource we have working on this.

Next meeting scheduled: Monday 29 April 16:30 - 17:30 BST

Is there a good place to add additional terms that come up, that are not currently included in the first sheet of Drupalisms?

Meeting on 29 April 16:30 BST. Attended by @emma-horrell and @rkoller

Notes here:
Drupalisms meeting progress log

Summary:
Continued noun foraging from admin UI to ensure we have a complete list of terms

Next meeting scheduled: Monday 13 May 16:30 - 17:30 BST

Thank you all for looking into this, having precise and immediately, intuitively understandable wording will help Drupal beginners a lot, and also just help people in need of a CMS solution more easily assess if Drupal is the right match.

@cellear: Thank you so much for putting the Drupal Site Builder/Developer-issue into words, it's something I have also been thinking about.

An expert Drupal Site builder who knows Drupal deeply, and can do some basic coding, or reach out to an expert PHP programmer if needed, really is what many projects need. Not a full fledged coder, who can churn out custom code all day long. While that is a great skill, the solutions you can build using tried and tested and constantly updated modules can often work very well, long into the future.

So yes, phasing out "Drupal Site Builder" for "Drupal Developer" is worth aiming at.

For me, when I started working with Drupal at the beginning, I always confuse between plugins and modules.
I used to work with Wordpress CMS and what we call "Module" in Drupal is called "Plugin" in WP.
Drupal use both terms "Module" and "Plugin", but what plugin means in Drupal is different : it allows to extend fonctionnalities of a module...

Meeting on 13 May 16:30 BST. Attended by @emma-horrell @rkoller
Meeting on 20 May 16:30 BST. Attended by @emma-horrell @rkoller and @dead_arm

Notes here:
Drupalisms meeting progress log

Summary:
Continued noun foraging from admin UI to ensure we have a complete list of terms.
Identified the need to log introduced terminology in the Drupal core new issue template to keep track of new terms as they come in (issue opened by @dead_arm (3449694)

Next meeting scheduled: Monday 27 May 16:30 - 17:30 BST

Meeting on 27 May 16:30 BST. Attended by @emma-horrell @rkoller @worldlinemine @AaronMcHale

Notes here:
Drupalisms meeting progress log

Summary:

• Updated the issue to log introduced terminology in the Drupal core new issue template to include link to controlled vocabulary spreadsheet so all can view to assess whether terms are new.
• Continued noun foraging from admin UI to ensure we have a complete list of terms. Made some adjustments to the collection process to ensure terms are categorised and more searchable than they were previously.
• Discussed ways to link this work to the impetus to make Drupal more inclusive and a more attractive proposition to CMS deciders. @emma-horrell to investigate requirement for user testing of Drupal Starshot

Next meeting scheduled: Monday 10 June 16:30 - 17:30 BST

Not the same goal but this is related.

"Introduced terminology" is now a section included in the Issue summary template, https://www.drupal.org/project/drupal/issues/3449694 📌 Add "Introduced terminology" section to the "Bare issue summary template" default heading for new issues Fixed . Documentation for the section is available in https://www.drupal.org/docs/develop/issues/fields-and-other-parts-of-an-... →

Two special tags are available now, "Terminology addition" and "Terminology change". Documentation about the tags is included in https://www.drupal.org/docs/develop/issues/fields-and-other-parts-of-an-... →

Meeting on 22 July 16:30 BST. Attended by @emma-horrell @rkoller @dead_arm @AaronMcHale

Notes here:
Drupalisms meeting progress log

Summary:

• @emma-horrell and @rkoller still continuing with the noun foraging - 616 nouns so far with additional verbs and adjectives.
• The tags "Terminology addition" and "Terminology change" had not showed any additions or changes since they were made available.
• Poll to be run in Slack channel #drupalisms-working-group to check if Mondays at 16:30 (BST) are still the best time for the regular meetings or if Fridays at 16:00 (BST) would be preferable

ACTION:
From the terms already collected, all to think about terms which would be good candidates to include in the quiz. Good candidates for terms will be one which:

• Have more than one meaning in different contexts
• Seem straightforward on the face of it but are more complex
• Are very specific to Drupal and not seen in other CMSs

List of candidate terms to be started in the Slack channel #drupalisms-working-group

Next meeting scheduled: Monday 5 August 16:30 - 17:30 BST

Meeting on Monday 5 August 16:30 BST. Attended by @emma-horrell @rkoller @dead_arm @AaronMcHale.

Notes here:
Summary:

• Poll showed Mondays at 16:30 to be the best time for a fortnightly meeting - so we will keep the meetings the same
• Aim to produce a terminology quiz to share with the community ahead of DrupalCon Barcelona (aim for w/c 16 September)
• ACTION: All to suggest questions to include in the quiz that test understanding of Drupal terms

Next meeting scheduled for Monday 19 August 16:30 BST

Meeting on Monday 19 August 16:30 BST. Attended by @emma-horrell and @rkoller

Notes here:

Summary:

• Noun foraging still to be completed on sections of the admin UI
• Given the timescales we will not have this complete in time to produce a top tasks survey for DrupalCon Barcelona as planned
• We still plan to launch a terminology quiz - to achieve this we need to source more questions, finalise the questions and finalise the wording. Plan to finalise quiz by 9 Sept, test it and then launch in the week beginning 17 Sept ahead of DrupalCon Barcelona

ACTIONS:
@rkoller had reached out to others in the community to supply questions, he will chase them up
@emma-horrell to set up a Doodle poll to share in the #drupalisms-working-group channel - for a 2 hour session in week beginning 2 September to finalise the questions for the quiz and the wording.

Next meeting scheduled for Monday 2 September 16:30 (BST)

BoF held at DrupalCon Barcelona 2024 (https://events.drupal.org/barcelona2024/session/opening-drupals-terminology)
After an introduction to the issue and sharing the quiz and another definition exercise, these topics were discussed:

• Use of change records to ultimately make changes to terminology used within Drupal
• Quiz and the responses received so far
• Other sources of ‘official’ terminology which we could refer to to help us work towards a standardised naming system/controlled vocabulary for Drupal. Suggestions included: Schema.org, ATAG guidelines. W3C guidelines and HTML terminology
• Opportunity of Starshot/Drupal CMS to avoid confusing terminology and embed good terminology practices from the start, both in the UI and also in accompanying documentation. Suggestion for a template for new issues, and also for modules to ensure a consistent approach to terminology. The new ‘sponsor a document’ drive may also help ensure that documentation is written in plain language without confusing terminology. To achieve this relates to points made about buy-in and convincing/educating key stakeholders in the Drupal community of the benefits of this approach. Plan to follow the documentation initiative to look for opportunities to embed/link to the Drupalisms work.

Meeting on Monday 30 September 16:30 BST. Attended by @emma-horrell @rkoller @dead_arm and @AaronMcHale.

Notes here: Drupalisms meeting progress log

Summary:

• Discussion around use of change records to ultimately make terminology changes within Drupal
• Highlighted need to educate and convince key stakeholders from the Drupal community (e.g. core committers) on importance of consistent terminology when it comes to getting buy-in to make changes
• Proposal to initiate change on a small, defined part of the UI as a way to test the change process
• Plan to promote quiz in different networks until it closes on 31 October
• Plan to set up a separate meta issue to cover the quiz to ensure completers can be credited and action following the quiz can be properly managed

ACTIONS:
All to promote the quiz on a scheduled basis, reaching out to groups including accessibility, usability and Drupal novices
@emma-horrell to set up separate issue for quiz
@emma-horrell to suggest another date to continue noun foraging with @rkoller

Next meeting scheduled for Monday 14 October 16:30 (BST)

Meeting on Monday 14 October 16:30 BST. Attended by @emma-horrell @rkoller @dead_arm and @AaronMcHale.

Notes here: Drupalisms meeting progress log

Summary:

• Plan to open new issue specifically for the quiz to point refer people to if they have questions
• Continue to promote quiz to get the most responses possible
• Plan to close quiz on 31 October and then work on assigning credits

Next meeting scheduled for Monday 28 October 16:30 (BST)

Meeting on Friday 1 November 15:00 BST. Attended by @emma-horrell @rkoller @dead_arm, @worldlinemine and @AaronMcHale.

Notes here: Drupalisms meeting progress log

Summary:

• Quiz now has it's own issue: https://www.drupal.org/project/drupal/issues/3480953 📌 Drupal terminology quiz Active
• Emma presented on this work at DrupalCamp Scotland (https://camp.drupal.scot/). Good engagement from attendees and suggestions to link this work more strongly with Drupal CMS and with the 'Adopt a document' drive
• Quiz has succeeded in raising awareness of this work and collecting a very rich dataset
• We plan to do some initial analysis for a high-level summary with a follow-up of a deeper analysis (Thomas to apply data science techniques and expertise to this
• Emma and Ralf to find a date/time to continue with noun foraging

Next meeting scheduled for Monday 11 November 16:30 (BST)

@h_kac: Your comment about the overlap of naming of concepts in WordPress and Drupal, and the confusion it may cause new Drupal users got me thinking: Wouldn't it be great with a page, which relates terms and concepts between WordPress and Drupal?

So I created https://www.drupal.org/docs/contributed-modules/wordpress-migrate/wordpr... →

Anyone should feel free to expand with more sections :)