[UX] text cleanup on new block administrative label/description

[jenlampton]

This is a follow-up to https://github.com/backdrop/backdrop-issues/issues/4558 where we introduced the shiny new admin label and description setting for all blocks :)

Current text is as follows:

• Fieldset title: Admin label
• Fieldset description:
• Label label: Admin label
• Label description: Used to identify the block on layout pages.
• Description label: Admin description
• Description description: This text is used only in administrative interfaces. It will not be shown to site visitors. Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>

Proposed text for each:

• Fieldset title: Administrative interface
• Fieldset description: This text is used only in administrative interfaces. It will not be shown to site visitors.
• Label label: Administrative label
• Label description: Used to identify this block on layout pages.
• Description label: Administrative description
• Description description: Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>

Reasoning:

• Fieldset label applies to both label and description, choose the less specific term Administrative interface
• I'd like to use the full word Administration instead of Admin wherever possible.
• The text This text is used only in administrative interfaces. It will not be shown to site visitors. applies to both fields, so move it into fieldset description?

Feedback?

---

PR: https://github.com/backdrop/backdrop/pull/3287

[jenlampton]

I've filed a PR that makes the above changes to the text, but it also changes the text block class to alter the block class admin info fieldset, rather than overwrite it entirely. (This will prevent us from having the same text strings in two places, so if we need to make changes in the future we won't need to remember to get both locations.)

[klonos]

The text This text is used only in administrative interfaces. It will not be shown to site visitors. applies to both fields, so move it into fieldset description?

Yup, I like that 👍 ...but the same applies to the Used to identify the block on layout pages. bit. Right? So why leave that only as help text for the label only, when it also applies to the description?

If we added that bit to the fieldset, we'd end up with this:

Used to identify the block on layout pages. This text is used only in administrative interfaces. It will not be shown to site visitors.

That's basically what I proposed in #4558: that we move all text that applies to both the label and description in the fieldset instead (except for the allowed HTML tags for description). Slightly tweaked from my proposal there:

This text is not shown to site visitors - only in administrative pages. It can be used to identify this block when multiple variations of it are added on the same layout.

[jenlampton]

...but the same applies to the Used to identify the block on layout pages. bit. Right? So why leave that only as help text for the label only, when it also applies to the description?

Interesting, I was thinking that the label was the identifier for the block, but not the description. I guess it could be interpreted either way... I liked having the description text on the label field so that I'd know what to put in it. But I could be convinced that it's self explanatory... :)

[herbdool]

This should be 1.17.0 since the feature was added there.

[olafgrabienski]

Are both elements only used to identify a block on layout pages? If they're used nowhere else, we wouldn't need the quite abstract term "administrative interfaces".

[quicksketch]

For reference here's what Views does (which is similar functionality):

Though IMO there's very little about the Views approach we'd want to copy.

[jenlampton]

we wouldn't need the quite abstract term "administrative interfaces".

@olafgrabienski would you prefer "the layout administrative interface"? It's more specific, but also more verbose.

[olafgrabienski]

My idea was to omit the whole "administrative" part. Something like this:

Used to identify the block on layout pages. It will not be shown to site visitors.

[jenlampton]

Used to identify the block on layout pages. It will not be shown to site visitors.

The problem I have with layout pages is that it doesn't distinguish between back-end and front-end. My home page is a "layout page", but I don't want my admin-label to be shown to people viewing the home page.

How about something like Used to identify the block when configuring layouts? Remove the concepts of pages and visitors entirely?

[olafgrabienski]

How about something like Used to identify the block when configuring layouts? Remove the concepts of pages and visitors entirely?

I like the direction but there are still some issues:

• Actually, "configuring" a layout doesn't mean managing blocks but choosing a layout template on pages like admin/structure/layouts/manage/default/configure.
• How does "when configuring layouts" sound for a native speaker? For me, it sounds a bit awkward (also when I translate it to German).

The problem I have with layout pages is that it doesn't distinguish between back-end and front-end.

Understood! However, I still think a noun would be a good fit. It just seems we don't have a good name for pages like admin/structure/layouts/manage/default (title is the layout name, active tab is "Manage blocks"). Ideas how to call them in this context?

[jenlampton]

Yeah, the name we have for all these pages is "administrative interface" but that's quite verbose.

[philsward]

Two points to bring up:

1. I did the "wife" test between the current proposed implementation and a proposal to what I feel like, makes a bit more sense (I agree with Jen that Administrative interface" is a mouthful.)

The wife said "the first one makes no sense to me". "The second one uses lingo I can understand".

In regards to asking about interface vs options, she said: "I have no idea what it means by interface".

2. This appears to only transfer to existing blocks. I created a new custom block and was met with the stable text like Admin label, Admin description etc, so this needs to apply as well over to custom blocks.

[philsward]

Sidenote question: is there an API where core and contribs can call on this "admin interface" so it is uniform across all of Backdrop?

[klonos]

I like uniformity/consistency with what we have in views. How about this?:

This text will only be displayed on the "Manage blocks" page. It might be useful if you place the same block type twice.

[jenlampton]

How about something like Used to identify the block when configuring layouts?

Right, we use manage for that.

the "Manage blocks" page

Of course @klonos already thought of this :) How about each manage blocks page since there is not just a single one of them?

Sidenote question: is there an API where core and contribs can call on this "admin interface" so it is uniform across all of Backdrop?

That's an interesting idea. There are so many things that have both a label and a description, we could make a generic form API element that could be reused. I think we should make that into a follow-up issue though and kep this one focused on this particular interface.

[philsward]

That's an interesting idea. There are so many things that have both a label and a description, we could make a generic form API element that could be reused. I think we should make that into a follow-up issue though and kep this one focused on this particular interface.

Personally, I think it would be best to extend this to all of Backdrop and make it more of a standard to the way BD works. It should be available to contribs if they want to use it, but not a requirement.

That said, I feel like that should first be agreed upon as a proposed route and then figure out how the wording will work for "most" use-cases throughout backdrop, then it can be addressed on how each specific area needs to have wording tokenized for it's respective use.

(loose) Examples: Blocks Add a label or description to better identify this [block] on admin pages.

Fields Add a label or description to better identify this [field] on admin pages.

Views Add a label or description to better identify this [view] on admin pages.

• Add a label or description to better identify this [view_relationship] on the view admin page.

Taxonomy Add a label or description to better identify this [taxonomy] on admin pages.

etc.

Make the wording congruent, such that any time someone runs across it, they understand its purpose. Otherwise, if each respective task has it's own vocabulary, it can become confusing as-to what the goal is. "I think this is where I set my own name for easy identification? But... I'm not really sure because it says something different??"

I feel that once the global wording can be more appropriately addressed, this particular issue will either become obsolete or only necessary for adding very specific verbiage regarding blocks.

Another thought: How can the wording be conveyed so that non-programmers can easily understand it? I am all-to-guilty of bringing out my analytical side when I talk, but I think sometimes we get carried away with certain lingo that 35% of the userbase has a hard time understanding. Something to think about.

[stpaultim]

That's an interesting idea. There are so many things that have both a label and a description, we could make a generic form API element that could be reused. I think we should make that into a follow-up issue though and keep this one focused on this particular interface.

I am going to stay focused on the specific issue at hand and recommend that project wide changes be discussed in another issue. If anyone thinks we should not make this change until there is a generic form API element, please speak up.

I am ok with all the ideas that have been suggested. I do agree that "Administrative interface" is a mouthful. "Administrative options" or "Administrative settings" also work for me.

@philsward suggested: "Create a custom label and description to make it easier for admins to understand this blocks purpose in layouts."

Here is a tiny variation.

"Create a custom label and description to make it easier for admins to understand the purpose of this block while administering layouts."

It seems to me that the next step is for @jenlampton to update the PR incorporating the feedback here AND/OR for someone else to provide an alternative PR that includes this feedback. Right now, I'm loosing track of what to respond to.

I would support merging any of the ideas presented so far. But, I also don't consider this an urgent task as the status quo could be improved, but isn't awful (in my opinion).

[philsward]

Could we cut this down to:

"Create a custom label and description to make it easier for admins to understand the purpose of this block."

Some possible variations (translations may be an issue):

"Create a custom label and description that will make it easier for admins to understand the purpose of this block."

"Create a custom label and description so it's easier for admins to understand the purpose of this block."

[indigoxela]

@jenlampton some (possibly unrelated) tests failed and the links point to 404 - mind to close/open your PR to re-run Zen.CI?

[klonos]

The tests are failing indeed, but links to test details do not 404 for me 🤷🏼

@jenlampton I like all the code simplification/cleanup in block.text.inc 👍🏼 ❤️

[klonos]

...I've added a suggestion that should fix all failing tests: https://github.com/backdrop/backdrop/pull/3287/files#r625110525

@jenlampton ^^

[klonos]

I'm reading through this thread, trying to understand if we have consensus on the string changes, and if there is anything else to be done as part of this...

Re this comment:

I am going to stay focused on the specific issue at hand and recommend that project wide changes be discussed in another issue.

I agree with @stpaultim 👍🏼 ...lets solve this UX issue here now.

Make the wording congruent, such that any time someone runs across it, they understand its purpose. Otherwise, if each respective task has it's own vocabulary, it can become confusing as-to what the goal is.

I think that this idea has merit and will improve both UX and DX (I'm a big fun of UI consistency and code reuse where possible). @philsward can you please open a new issue, and copy-paste your suggestion from https://github.com/backdrop/backdrop-issues/issues/4600#issuecomment-730703477? Thanks

[herbdool]

I applied @klonos' suggested fix. All tests passing so I put it back to needs code review. So long as @jenlampton is okay with that small change.

[klonos]

The PR could use a rebase.

• This text will only be used to identify the block when configuring layouts. technically the layout configuration page does not have any blocks, so perhaps this is more accurate: This text will only be used to identify the block in the "Manage blocks" form..
• I thought that the It will not be shown to site visitors. bit was providing value to people that are new to Backdrop and layouts.

[jenlampton]

I thought that the It will not be shown to site visitors. bit was providing value to people that are new to Backdrop and layouts.

I find it confusing as there is no specific definition for "site visitors". It's also redundant because "This text will only be used to identify the block when configuring layouts." already states the opposite. its like saying "the switch is on, it is not off". You don't really need both to get the point across, and since less text creates a less overwhelming experience, I opted to remove the one that was more confusing.

I will rebase :)