[PP1] Refine field descriptions

I think that it would be good if we can consider the "File upload" group, which can be a bit confusing for users. The File and Image field types were separated for a long time, but now they are groupped together with a Label/Description that does not mention Images at all. I know that now there is also a Media field, which is preferred, but for example for migrating D7 users this concrete groupping can be a bit non-intuitive.

The file upload group was created based on a card sort exercise we ran earlier this year. The results we got from there were pretty clear that people tend to map both image uploads and file uploads together. That said, Media was a challenging one; some people listed it under reference and some people listed it under file upload. That's why we decided to move it to the main level to try to address this challenge.

One of the use cases we tested as part of the usability testing was image and media fields because we had similar concerns that it might not be intuitive. However, both existing and new users were able to find the fields and we didn't find any challenges with the current sorting so we decided to proceed with that.

We should decide also whether to use full stop for bullet points. This was raised as feedback in 📌 Date range should be in the date_time category Needs work .

Plain text
Current: Text field that does not support markup.
Proposed: Text field without markup support.

Formatted text
Current: Text field with markup support and optional editor. ✅

Number
Current: Field to store number. I.e. id, price, or quantity.
Proposed: Field to store a number value.

Reference
Current: Field to reference other content. ✅

Media
Current: Field to reference media. Allows uploading and selecting from uploaded media. ✅

File upload
Current: Field to upload any type of files.
Proposed: Field to upload a file of any type.

Selection list
Current: Field to select from predefined options. ✅

Date and time
Current: Field to store date and time values. ✅

Boolean
Current: Field to store a true or false value. ✅

Email
Current: Field to store an email address. ✅

Link
Current: Stores a URL string, optional varchar link text, and optional blob of attributes to assemble a link.
Proposed: Field to store a URL string.

Telephone number =>> Telephone (as the 'Email' field is not 'Email address')
Current: This field stores a telephone number.
Proposed: Field to store a telephone number.

I agree with #3, for me the images/file thing was a hard stop for some hours.

It was not very clear to me if image fields are references or uploads (and there is a bug in the UI ( #3415799 🐛 Creation of new image fields not possible in new field UI in non-english UI Active ) right now that makes it undiscoverable through try & error clicking in the UI).

After the usability meeting 📌 Drupal Usability Meeting 2023-09-29 Needs work I've started a Google sheet based on the discussions during the meeting, did some additional testing of my own, and discussed the matter at the Drupal Dojo Austin twice. But I haven't posted it yet because the draft wasn't anywhere near finished and I haven't found any time revisiting the issue since then. But used the time over the Global Contribution Weekend and the following days to get to a rough draft as well as write up this comment summarizing the outcome.

In regards of the question raised in #5, I would say it depends on the bullet points. If they are full sentences use the ending punctuation, in case they are no complete sentence then don't use the ending punctuation - that would be my rule of thumb.
As in case of the options bullet points should provide an easy to scan overview to the user. I would vote to go with the no complete sentence variant, therefore no periods at the end. And the goal should be to make the bullet points as concise and skim-able as possible imho.

About #3 📌 Refine field descriptions Active and #7. I had a similar experience like @hudri, at one point I needed to test something in regards of images and had a really hard time figuring out that images are actual within File upload - completely unexpected. Due to the term File in File upload I haven't associated the group with images at all.
And at first I also agreed with @lauriii in #4 📌 Refine field descriptions Active that media is tricky to sort because it would fit into reference as well as file upload. But on second thought, and after investigating more into how File, Image, and Media reference fields function, I now think there might be another option. Move Media into the currently called File upload group. All three field types are reference fields (also see /admin/help/media) and all three provide the ability to upload an asset. In regards of the micro copy File upload was closely linked semantically to the File option, the reason Image was unexpected for me to find there. By renaming File upload to the more generic term Upload it would wrap the File, Image, and Media field types nicely. And by referencing the term media in the description of the group Upload it would also be taken care of that the context for Upload clearly is Media related.

The observations in regards of the microcopy:

A) Step 1 - Field type descriptions:

1. The label Choose a type of field could be shortened to Choose a field type
2. In most of the descriptions the front loaded phrase "Field to" is sort of redundant plus the term field should ideally be avoided if possible since the overall context is already set by the page title.
3. Another redundancy is between the title and the description. If you strike cases of "title", "field to", "field", and related from the description most often there is not much extra information left. A detail that was raised during the Drupal Dojo in Austin.
4. In regard of readability and plain language, latin as well as abbreviations should be avoided. One example is "i.e." in the description for the number field type.
5. Not directly micro copy related, but I've noticed it is sort of difficult to distinguish from the list of available options what is a group and what is a field. There is neither a visual nor a micro copy based cue. Might be helpful for people exploring the options, under which option you get to a list of field type options and under which you get to the field settings of the chosen field type.

B) Step 2 - Field type options:

1. The label Choose an option below is using directional language, instead simply Choose an option could be used. Technically Choose a field type would be more accurate her as well?
2. The readability of the option labels is sort of challenging. First you have the redundant field type label and then the information of interest wrapped in parenthesis. A potential fix might be to remove the label and the wrapping parenthesis and front load aka more or less reverse the order of the content in parenthesis. For example Text (formatted, long) becomes Long formatted. Or another option might be instead of removing the label outside the parenthesis to append it at the end so you would get Long formatted text. But the overall context is already set in the page title or dialog modal title so that "probably" would not the best choice and introduce another redundancy.
3. The order, style and components of bullet points differ across options. Not sure if it is a good idea to start off with what a field is ideal for as the first bullet point as not even all options contain it. How about the following order, provide an outline about noteworthy characteristics/details for an option, then an example (same like "ideal for" there aren't examples for every option), and then at the end what the field type is ideal for? Instead of providing an example, one idea and feedback that was brought up during the Drupal Dojo Austin, was to provide what would be the corresponding html tag that the chosen field type creates/puts out (problem with that suggestion, that information would be available and make sense only for a few of the available options). In combination with the points listed in step 1.2 and 1.3 it was considered challenging to immediately know which field to pick when building the fields for a content type.
4. One detail I've noticed while going through all field types for the draft Number (decimal) doesn't communicate in anywhere that the maximum precision is at 32 and scope at 10. You only get informed about that detail by an error message after you've tried to enter a bigger value on its field settings page. I've added a bullet point about that to the Number (decimal) option in the draft. But it might be also a good idea to add that information to the descriptions for precision and scale on the field settings page as well in a follow up?
5. The description for File upload and Media currently has two flaws. For one with 📌 [PP-1] Move label and machine name fields to the field config edit form Active only File upload will have three steps with the description on the second step. And in general that description would be way more useful to the user before making the decision if File upload or Media is the right choice, not after the initial decision was drawn and the user already moved onto step 1. Perhaps it might make sense to remove the description from step 2 entirely. I've tried to spread the relevant information to the descriptions in step 1 and the descriptions for the corresponding options in step 2. Plus as noted in the other issue #3397711-16: Move label and machine name fields to the field config edit form → it might make sense to add a description pointing to a to be created help topic providing an overview of all available field types and when to use which field type best on top of the page right before the Choose a type of field.
6. The Reference options might be considered to be removed. For one none of the options has any information with bullet points. Each of the options only stands for a different preselected referenced entity on the field settings edit form. Aside that there is no real apparent difference between the four. Plus the Other option references the same preselected option that Content also does. Content and Other are practical identical configuration wise. And the term Other is way too generic and meaningless. One option might be to at least rename Other to something like Custom. But the more reasonable approach might be to remove all four Reference options as initially suggested. Or is there a detail I've missed about those Reference options?
7. The examples provided for the three Selection list options are outdated, they are only suitable for the old UI that contained a textarea. The UI has fields in place instead now and the instructions for the old text area UI pattern therefore increase the cognitive load and create potential confusion how to apply those examples. In addition, in the current form the examples are challenging to skim and comprehend for screenreader users.

The link to the aforementioned Google sheet is: https://docs.google.com/spreadsheets/d/1Lx7L40eRHotr5KQGn6au5WxQO3lFv19a...
Everyone with the link has editor permissions. I've created a sheet for each step. On top of each sheet there is the list of potential issues listed in this comment. For the first step the first two columns, for the second step the first column contains the current state of the micro copy. The columns right next to them contain suggestion. Having more than a single column for the draft has the advantage that you are able to spot any consistency and redundancy related issues easier across the spreadsheet, and having dedicated columns for the different suggestion makes it easier to get inspiration and iterate faster instead of getting the older version replaced on every iteration.

And I've also added the issue to the shortlist for one of the next usability meetings. Last Friday we haven't had time to get to it unfortunately.

Usability review

We discussed this issue at 📌 Drupal Usability Meeting 2024-02-02 Active . That issue will have a link to a recording of the meeting.

For the record, the attendees at the usability meeting were @benjifisher, @duncancm, @rkoller, @shaal, @simohell, and @worldlinemine.

We've covered only Step 1 - Field type descriptions<code> and agreed to iterate asynchronously on that step as well as do the same for the second step <code>Step 2 - Field type options. A few takeaways from the discussion about step 1:

• In general the group was in line with the problems and draft I've posted. But the consensus was to shorten draft of the descriptions further and drop even the front loaded verbs. That way the descriptions would be briefer and no full sentences anymore, therefore the period at the end cloud be dropped as well.
• One detail raised in the context of text fields was the idea to combine plain text and formatted text. In case a user isn't clear about the difference one might end up in the wrong group. With a combined group for text fields all available options for plain and formatted text would be available in the second step.
• One suggestion that was brought up, for inspiration taking a look how other CMSes describe their fields (the examples that were raised during the meeting for WIX and Contentful don't describe the functionality but simply provide examples instead). I still have many test sites installed from the navigational hierarchy spreadsheet https://docs.google.com/spreadsheets/d/1o8JV3Qck92mV3CtoGdiRdqeRiW2L3Jk6... . I 'll investigate over the weekend if i am able to find and come up with more examples to compare with.
• Another suggestion that was brought up was to use ChatGPT and or Bard. It was clarified that none of these LLM based strings should be used as is. They should solely provide some sort of different perspective and provide inspiration. @worldlinemine already added the examples for the field type label and the field type description for Bard in column F & G on Step 1 - Field type descriptions
• In the context of the Media field type @simohell provided the sheet for the field classification exercise https://docs.google.com/spreadsheets/d/15AtAgvHaYZ1FfjpGNpuRctZDsIRuCp1DQV6hoi9YqTI/edit#gid=0 (. We haven't really discussed the problem of the sorting of the Media field type but the need for a clarification raised here is in line with the comments in this issue as well as the points i've made in step 2.

Odd, I've uploaded the screenshots for Wix and Contentful already in the previous comment but somehow the two files weren't available in the files fieldset. And after posting only the wix.jpg got upload. Instead of editing the previous comment I'll add a new and add the images here as an addition to #3370326-9: Refine field descriptions →

Adding a new field in Wix:

Choose a field type in Contentful:

Adding related issues that cover part of the topic here, when we started this discussion in the realm of Media/File/Image fields and the confusion this generates:

🌱 [META] Once media is enabled, having the File, Image and Media reference fields all listed is confusing Active
#2930446: [PP-1] Improve field description texts for fields provided by core →

Also wanted to point out that a media field can be used for remote video content (a Youtube video for example). In this case, the "Upload" term isn't quite a good fit, IMO. On the other hand, some sites might have the option to store the videos "locally", instead of relying on a 3rd party service, in which case it would make sense to "upload" a video file into a media field.

Changed the parent issue to 🌱 [Plan] Improve field creation experience Active ,which is still active, in contrast to ✨ Make field selection less overwhelming by introducing groups Fixed which is closed and fixed. for a while now. otherwise this issue might slip through.

Usability review

We discussed this issue at 📌 Drupal Usability Meeting 2024-10-25 Active . The link to the recording of the meeting is https://youtu.be/yuaPVd6Lgv0. For the record, the attendees at the usability meeting were @avani.bhut, @benjifisher, @rkoller, @rosendofig, @shaal, @simohell, and @worldlinemine.

And we have discussed this issue another time at 📌 Drupal Usability Meeting 2025-01-03 Active . That issue will have a link to a recording of the meeting. For the record, the attendees at todays usability meeting were @benjifisher, @rkoller, and @simohell.

In both meetings we’ve continued the wordsmithing of the micro copy for the field type options in the second step of the field creation flow. The work in progress can be found in column C in the spreadsheet (https://docs.google.com/spreadsheets/d/1Lx7L40eRHotr5KQGn6au5WxQO3lFv19a...). We plan to continue reviewing the current draft found in column B/D in the upcoming meetings in case no other issues come up.

At 📌 Drupal Usability Meeting 2025-01-10 Active , we continued work on the spreadsheet (see Comment #13). For the record, the attendees at the usability meeting were @benjifisher, @rkoller, and @simohell.

We continued the word-smithing at 📌 Drupal Usability Meeting 2025-01-17 Active : @aaronmchale, @benjifisher, @rkoller, @simohell, and @worldlinemine.

We continued the word-smithing at 📌 Drupal Usability Meeting 2025-01-24 Active : @benjifisher, @rkoller, @simohell, and @worldlinemine.

@rkoller, @worldlinemine, and I continued the word-smithing at 📌 Drupal Usability Meeting 2025-02-07 Active .

The draft of the MR is a work in progress, reflecting proposed changes we've discussed over the course of several ux meetings. The MR is not complete and ready for review yet - we plan to finalize the MR in the coming weeks. We've considered it helpful at this point being able to see all the changes in context. A few remarks:

• So far i've only added the discussed changes for the available field group options, but all those changes also rely on changes on the h1. At the moment the first two steps are just called Add fields across all field types and field groups. ✨ Use modal in add new field flow Active has to get in first for that. After that the proposed changes for the h1 on second step could be added as well.
• While making the changes for the MR I've noticed that the changes on the field type/field group labels also entail necessary changes in help texts and tests. But those changes should happen after a final consensus was reached about the micro copy. Leave it here as a reminder.
• It has to be noted that at this point the description for every option available for the reference field group has an identical description defined in EntityReferenceItem.php. That way it is impossible to provide some sort of guidance to the user what the actual difference between the different reference options actually is and which option to pick in which scenario. So we probably need a separate issue to add the ability to provide individual descriptions for the different reference options.
• The file upload field group currently has no description yet and is still using the pattern starting with "field to..." we've removed on the description for every other field type and field group. But the entire question how to deal with the media field type is out of the scope for this issue and complicates everything. @benjifisher already opened 📌 Add media reference to the same field type group as file and image Active a few weeks back - the general discussion and work should happen there.

We continued the discussion at 📌 Drupal Usability Meeting 2025-02-14 Active : @benjifisher, @rkoller, @simohell, and @worldlinemine.

It turns out that Selection List is more complicated that I anticipated.

At 📌 Drupal Usability Meeting 2025-02-21 Active , we discussed the text for Selection Lists: @aaronmchale, @benjifisher, @simohell, @worldlinemine.

There is already a MR for this issue, so I am setting the status to NW.

I was afraid that getting different messages on the various Entity Reference fields would be difficult, but it is actually pretty easy. I added a commit. Now, we just have to decide on what text to use. Personally, I think none of the options should have description text except for Other.

We discussed the text for the Date and Time option at 📌 Drupal Usability Meeting 2025-02-28 Active : @benjifisher, @rkoller, @simohell, and @worldlinemine.

I rebased the MR. The only conflict was from 📌 Fix DrupalPractice.Objects.GlobalFunction in hooks Postponed , which replaced t() with $this->t().

@rkoller:

On Slack, I said

My commit changes core/lib/Drupal/Core/Field/PreconfiguredFieldUiOptionsInterface.php. Just search for the classes that implement that interface and add a description key to getPreconfiguredOptions(). (Or search for that function.)

I was wrong. It is more complicated than that.

I just pushed a commit that implements the Usability team's recommendations for reference fields. I mostly followed the example of hook_field_ui_preconfigured_options_alter() in core/modules/field/field.api.php.

thank you! that is definitely beyond my skill level to figure out on my own :D will add the rest of the strings tomorrow. need to get some sleep first.

I've pushed the remaining changes we've discussed over the course of the last few weeks. The are still strings on the google sheet that still need to go in:

1. I was not sure how to add a help text to the second step for selection lists. the proposed microcopy for the help text is: Each list item has a Name, with limited formatting, and a Value. Values that are in use cannot be changed, since they are stored in the database. The Names can be edited later.
2. it has to be kept in mind that this issue needs additional work after ✨ Use modal in add new field flow Active goes in, cuz at the moment the h1 on the page isnt changed and adjusted but it has to (and we also prepared suggestion for what could/should be used in the title of the dialog modal.

A few more details about the current state i've noticed applying the changes and going through the interface again:

• for some field groups there is the problem on the second step that the order of options is alphabetical but it would be better to order them in a different manner. for example for plain text the labels were text(plain) and text(plain, long), so short was first and the more complex second. with the new labels short text and long text, long text comes first.
• for the long text option for formatted text it might make sense to make a characteristic for text areas more explicit. short text states that text fields are oneliners while long text just says it uses text areas for input instead. it might be reasonable to clearly communicated that text areas are multi-line?
• I've removed the periods at the end of each bullet point on the reference field options. we havent used periods on the bullet points for any other fields.
• would it be possible to add a bullet point to the other reference field? it looks odd without any.
• on date and time field types it is not entirely clear what the examples refer to. are those the format date and time has to be entered or is it the example in what way dates and time are stored in the database - it might be misinterpreted.

The MR needs a rebase after ✨ Use modal in add new field flow Active went in

I rebased the MR. One change that got lost is replacing "Choose an option below" with "Choose an option". I think that #3386762 changed it to "Choose a field type":

I think that is good.

I did not test much, but I did look at the Reference options, and I think our changes are still there.

Based on Comment #27, the status should still be NW.