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.