Make Description Field Labels Consistent

The Block type description field label is already updated. Screenshot attached. Changing the description field label only for the Add menu Page.

I can confirm 2 things are fixed.

• Block description has been fix. I ran grep -rnw ./ 'Block description' and got no results
• See attached screenshots for before and after images of the patch fixing the description.

I'm wondering if "Administrative summary" would be a better label for these fields because it describes what the description is used for. It looks like "Add menu" description was labelled as "Description" in the past, and was intentionally changed in #1926692: Menu description is misleading to allow for multiline input.

I can agree with that I think.

Hey guys, I wasn't sure whether the changes to "Administrative summary" was agreed for all of the fields in the table in the original description. Or whether it was just for the two Menu and custom block.

I've added an MR which addresses the Custom block.

Happy to take another look if we want to change for all of the rows in the table. Cheers!

Thanks for working on this. Can you add your changes to the exciting MR though please

Kindly review the patch.

This issue was started in an MR and should continue there per policy.

@smustgrove, Unless I'm mistaken, it looks to me like @bharath-kondeti has added a new commit to the original MR, which addresses the issue: Merge request !4128.

Comment was for #14

But MR 4128 has a failure.

Understood, apologies. Don't have much experience with tests and failures but will take a look.

That one is odd will admit.

Hey @smustgrave,

Ran the tests again and they’ve passed this time.

Is this ready for review now?

Odd.

But should of also noted the MR and issue summary proposed solution do not match.

@smustgrave,

Didn't comments #7 and #8 update the requirements of the task to something different to the issue summary?

if that's the case the issue summary needs to be updated.

I here do not agree with the direction this thread has taken from #7.

I understand and support the IS as it was originally created.

The issue refered at #7 has targeted the multi-line nature of description field and as obvious going through that thread it clearly seems that they had discussed about reducing length of description field to change it to textfield supporting single line description, however the change in label was taken as granted without any discussion/consideration. This thread wanted to rightly streamline the labelling for description field.

10 years ago this got missed and I agree with Chris Matthews on this that the field label should be consistent, unless we have a strong case deviating from it.

Reasons to have consistency:
1) Go To
1.1) "admin/structure/types/add"
Notice description field label and the help text shown below the field.

1.2) "admin/structure/taxonomy/add"
Notice the description field label.

1.3) "admin/structure/menu/add"
Notice the description field label it simply stands out as "Administrative summary" why this in consistency.

If we were to indicate that this description will appear only at administrative page then for that clarification we have the provision to add
help text for the field, why change the field label altogether that too inconsistently.

2) Any mature application/software professes consistency and standardisation and I believe that this issue rightly progresses towards that.

Likewise at "block/add" page for description field why to have "Block Description" label when its so obvious, you are already at "Add content block" page just having "description" label is enough, for further clarification we may always add the help text.
On the contrary when you are at "admin/structure/block-content/add" the label for description field is just "description".

At "admin/structure/comment/types/add" also we have description label.

I think having consistent label is good and any meta about the field if needed can be provided as help text.

I'm at Drupalcon Lille, and working on this today..

Checked:

• /admin/structure/menu/add
• /admin/structure/block-content/add

Both are updated.

I don't agree that the label was changed in #1926692: Menu description is misleading to allow for multiline input without any consideration given that the issue started with the statement that "Description" label doesn't describe what it's used for. I'm not feeling too strongly about the label itself. However, if we want to revert the label, we need to come up with an alternative solution to address #1926692: Menu description is misleading to allow for multiline input.

Seems like a still NW issue.

We discussed this issue at #3397066: Drupal Usability Meeting 2023-11-03. That issue will have a link to a recording of the meeting.

For the record, the attendees at today's usability meeting were @AaronMcHale, @anmolgoyal74, @benjifisher, @ckrina, @rkoller, and @simohell.

If you want more feedback from the usability team, a good way to reach out is in the #ux channel in Slack.

In general, the group was in line with the gist of what this issue is about: consistency is a good thing. There was some discussion to iterate in a direction the term Administrative summary headed. To convey that the description is only used in the administrative interface. But there is a potential problem with the expectations a user might have with the term Summary. The term is usually used in the context of summarizing longer texts (for example "text formatted long with summary"-fields), which might bring up the question what is the original text it is summarizing? The term Administrative on the other hand brings in a certain weight. For me personally reading Administrative summary brought up the association and the expectation the entered text must be for something more important than a "plain" description for menu. We tried to come up with an alternative trying to convey that a description is only used in the administrative interface and that it's purpose is being a description. But that made the label even longer and more complicated. In the end the consensus was to suggest to stick to the following pattern already familiar to the user:

For the field label use:
Description

For the field description use:
Displays on [the place where the description will be shown]

*The field description was not directly part of the issue summary but while going through the pages we've noticed inconsistencies there as well because Add menu, Add vocabulary, and Add view are missing a description.

Overall going with the term description is the briefest most clear term most users are already familiar with and by providing a consistent field description the user always knows where the description will be displayed. By adding a field description to the Add menu page as well that would take care of the raised concern in #7. It would be basically be the approach outlined in the proposal section in #1926692: Menu description is misleading to allow for multiline input but the patch changed instead of adding a field description the field label to Administrative summary.

In regards of consistency two more points have to be noted that are probably out of the scope for this issue.

1. on /admin/structure/views/add aside the fact that the description field doesn't have a field description, that description field is also opt-in. You have to click the description checkbox before you are able to enter an actual description. No matter if a description is entered or not the description column is shown anyway on admin/structure/views. Instead of hiding the field behind an opt-in checkbox the suggestion is to directly show the description field on /admin/structure/views/add.

2. the adding a content block page surfaced a more general issue in particular if you apply the patch for #3325167: Revisit the redirect to 'add block' form in the 'add block content' form alongside.

• on block/add/basic?destination=/admin/content/block you see the required field Block description. Based on the label you could add a verbose description what a block is actually about like for example:
  

  Communicates the values of our NGO. The is being clear and vocal about them. So everyone visiting our website considering supporting us knows what drives us.

• click the save and configure button
• the block description you've just entered gets transferred into the title field on the configure block page and the machine name gets adjusted accordingly.
• pick a region in the select field and click save

=> you will run into an error message "Machine-readable name cannot be longer than 64 characters but is currently 139 characters long."

so it is sort of confusing that you are required to enter a description for the content block on the first page which is treated like the title on /admin/content/block where you dont have a title column like on /admin/content but a block description column instead. the expectation on the user end aside the described problem about the field length is the general role. the title is the label for an entity while the role of a description is to actually describe an entity label further in case the sole title isn't clear enough. by reversing the order and first requiring the description and then mirror the entered description to the title field complicates things further.

I'll add the need follow up issue tag and remove the needs usability review one.

Thanks @rkoller for taking this up in the Usability meeting and sharing the gist's here.

"consistency is a good thing", #24 I expressed my alignment with this (hopefully I am getting good at UX nuances :))
We may make the descriptions and labels consistent as suggested in #31.

For the field label use:
Description

For the field description use:
Display on [the place where the description will be shown]

I've just realized another inconsistency and place the term "Administrative" is used. When you create a view the term description is used on /admin/structure/views/add as described in the issue summary. But if you edit an existing view and you want edit its displays, the button is labeled with Edit view name/description. But within the dialog modal after clicking the button you have the field labels Administrative name, Administrative description (with a description for the field missing) and Administrative tags.