search

backdrop / backdrop-issues

Issue tracker for Backdrop core.
144 stars 39 forks source link

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

Open jenlampton opened 4 years ago

jenlampton commented 4 years ago

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:

Screen Shot 2020-09-03 at 1 35 57 PM

Proposed text for each:

Screen Shot 2020-09-03 at 1 43 02 PM

Reasoning:

Feedback?

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

jenlampton commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

...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 commented 4 years ago

This should be 1.17.0 since the feature was added there.

olafgrabienski commented 4 years ago

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 commented 3 years ago

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

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

jenlampton commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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?

Screen Shot 2020-09-15 at 5 24 04 PM
olafgrabienski commented 3 years ago

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:

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 commented 3 years ago

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

philsward commented 3 years ago

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.)

image

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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.

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

klonos commented 3 years ago

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 commented 3 years ago

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

@jenlampton ^^

klonos commented 3 years ago

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 commented 2 years ago

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 commented 2 years ago

The PR could use a rebase.

jenlampton commented 1 year ago

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 :)