[UX][D8] Make position of #description (help text) configurable via the API

[Graham-72]

This has been addressed in D8 core: #314385 Make position of #description configurable via the API, which makes this part of #378

D8 change record: https://www.drupal.org/node/2324025

For short form fields it makes sense to have the #description appear below the form widget; however, in long lists of checkboxes and/or radio buttons it would be nice to be able to have a toggle whether the #description appears above, or below, the form widget.

The is a new #description_display option with three allowed values, consistent with '#title_display': before, after and invisible.

There is no UI in core for toggling this behavior for existing forms.

Comment by a user in the D8 issue:

I'm very glad this issue has been addressed for Drupal 8.

People with low vision may use the site at an extreme zoom level, in which case the issue of the help text being below the field is exacerbated because they only see a very small portion of the screen at one time. Imagine the image in comment #47 but at 500% zoom. That's a TON of scrolling. ARIA doesn't really help users in this scenario.

Contrib modules that help with this

• https://www.drupal.org/project/label_help
• https://www.drupal.org/project/extra_field_description
• https://www.drupal.org/project/better_field_descriptions

---

Original report

I would like to see a field's description/help text appear above the field rather than after, as would surely be the case with forms in everyday life (i.e. non-Drupal/Backdrop).

I have just read Drupal 7 - Move field's help text (description) between the label and input element(s). Do we have a Backdrop view or decision on this?

See #1351 for one example.

Advocate: @herbdool

[mikemccaffrey]

It would be hard to evaluate whether this is a good change to make, considering the thousands of different use cases of descriptive text with fields of different types. And since having the help text below the field is a long-standing drupal standard, we should probably not change it on a whim.

Perhaps we should consider alternate ways to resolve this issue, such as a new setting for whether the help text is is above or below the the field inputs, a contrib module that makes the change across the entire site for those who want it, or better visual indication that the help text is tied to the field above it.

[Graham-72]

Fair enough, though for me it is a bit more than a whim. It is a significant UX irritation. @sutibun what do you think?

[sutibun]

Generally speaking, this is a UX fail.

1. Drupal/Bd is generally hard to understand and follow. It has a long history of not being the most intuitive CMS. I doubt many can argue this point.
2. Knowing that, you know users will eventually hit a UI element that will perplex them. They won't understand what to make of it. (read: friction point)
3. Now, because Drupal isn't well designed or user-friendly, you'll want, at the very least, to have the descriptive text nearby to explain what's going on. Having the help/descriptive text further away from the problem doesn't help this "painful" moment. You're now forcing the user to look around for help. This is what degrades the UX more than it should. A double whammy.

Here's a quick example from #1282 (think the search settings page?)

What does "active search modules" mean? Do you think a user would easily grasp the meaning behind this title? Not likely. This will cause confusion. I know because it confused me when I first encountered this not too long ago. Yes, in Bd. (Theory: if it confuses even me, it's likely normal users won't stand a chance)

Let's start from the beginning again.

So, a user will first read a confusing title, then still not knowing what's what will then encounter two checkboxes and then finally hit the descriptive text that provides the context and understanding.

Isn't that the wrong order?

Shouldn't the user first understand what is going before encountering any UI element? Of course! Presenting UI elements before the user orients him/herself is a recipe for confusion.

This wouldn't be such a big trouble if for the most part, Drupal was easy to understand. But it's not. More often that not, users will find lots of quirky things that need an explanation. So, this is why it's best to move the help text near the label so you'll get the following process

1. User reads title/label but doesn't get it.
2. User eyes then falls to the help text which provides context and understanding.
3. User finally sees the UI element but because now have the proper background info, can follow along even if the UI is a lil' quirky.

I am in the fortunate (unfortunate?) position where I am not an advanced Drupal user so I am still tripping over Drupal/Bd and experiencing these pitfalls. I think if you know Drupal/Bd well, this doesn't seem like a big deal but I'd argue it is.

And since having the help text below the field is a long-standing drupal standard, we should probably not change it on a whim.

"a long-standing drupal standard" That isn't a good argument. "Standard" makes it sound nice and authoritative... something not to challenge. But that is far from the truth.

Standard just means it's what been done for ages BUT Drupal isn't exactly the most friendly CMS so more reason to change how it was done.

Having said that though, ultimately the best solution is to design Bd so it's more user friendlier and intuitive so we won't have to rely on help text. The moment you HAVE to explain a design element, that's a sign you still have more work to do. To me help text is a crutch. But since it'll take time to refine Bd, moving the help text closer is a step in the right direction. A short term gap.

My two cents.

[Graham-72]

I share strong feelings about this. And it is not just about what one might call internal settings within Backdrop/Drupal. When building a site with quite complex data fields some help text is often needed to explain what the owner of the site must do to add content. Here is part of screenshot for a real life Backdrop site (a book store) where my client adds details about a book. Of course it is not a problem now that she has learnt where to look for the explanation, but it is not intuitive to look below the fields and requires supplementary notes for other staff in the book store.

[sutibun]

Of course it is not a problem now that she has learnt where to look for the explanation, but it is not intuitive to look below the fields and requires supplementary notes for other staff in the book store.

What this means is she has adapted to Bd's quirkiness. Or really, just puts up with it. Although it might seem small but this tiny friction contributes to the feeling that Bd is just hard to work with. Little by little these things add up to overall frustration.

[klonos]

The underlying issue here is that different "level" of users expect different things...

• Newcomers would rather help text to be top-most so that they read an intro. Especially in pages that require deeper knowledge of Drupal/Backdrop internals, workflows and terminology.
• Veterans (or newcomers once they've learned a thing) would rather the text be out of their way, less page clutter and less scrolling.

So the question is: "Do we target newcomers or old-timers?" and as a side-question: "Can we find a way that sorts this issue for both?"

I do not have the answer for these questions. Perhaps as a veteran I get a bit selfish and tent to ignore the needs of people trying to learn Drupal/Backdrop in favor of getting things faster and having a cleaner UI.

Here's what this situation got me thinking though... in some video games there is a "Show tooltips" or "Enable tutorial" checkbox/mode. Can we have a "sticky" ❓ help icon that gets the help text out of the way (completely - all of it!)?

Thoughts?

[klonos]

...how about help icons next to each element that shows the help text as a tooltip on hover (click on mobile, touch devices)?

[klonos]

@Graham-72 having markdown links point to domain+path without the leading http://www (or simply the www alone) causes them to render like https://github.com/ + GitHub path where the link was created + path entered, so your link was pointing to https://github.com/backdrop/backdrop-issues/issues/drupal.org/node/2319111 which of course 404s. Fixed that for you 😉

[klonos]

Just as a reference, there is https://www.drupal.org/project/beautytips that works by revealing a help text balloon/tooltip upon field focus:

(personally don't like this solution because it does not give any visual indication that a help text is actually available).

[klonos]

Here's a few more articles/screenshots of similar things to what I proposed:

https://ux.stackexchange.com/questions/53950/helptext-area-vs-help-tool-tip-icons-on-click

http://howto.caspio.com/datapages/datapage-components/field-configuration-options/rollover-hints/

https://www.drupal.org/sandbox/guillaumev/2074309

CiviCRM example of a form with help icons/tooltip:

[Graham-72]

Thanks for all those references @klonos - plenty to think about.

Perhaps we should also look at what Wordpress offers its users. I don't know whether this is typical but how about this example taken from a narrow right-hand column:

[klonos]

You see, I understand that this provides the instructions for people that have not used this before, but once I have done it once and I am familiar with how to do it, then this rather lengthy text is in my way and simply adds clutter. I would like to get it out of my way. Now, if all this was to be "hidden away" under a ❓ or ℹ️ icon next to the field label and only shown once someone actually clicked there, it'd be perfect.

This design as is assumes that everyone would need this info available all the time. That is not true though. Think MS Office and the paperclip: most everyone though it has cute and helpful at first, but when you had it coming again and again telling you the same tips over and over while doing the same task, it got annoying.

[Graham-72]

Yes, perhaps it is a poor example of useful text (too much of it) but at least it is above the field.

[klonos]

...perhaps it is a poor example of useful text (too much of it)

Precisely why I'm not particularly font of inline help text. If we have a general standardized way of placement (either above or below elements) throughout the entire UI, although it might be ok with small portions of text, it gets really messy with big help text ...especially in small screens.

If you have strong feelings about getting the help text as close to the label of the fields, I believe that we can explore two different ways implementation-wise... either have the help text in a pop-up tooltip that pops close to the field or have it so that the help text is inline with the rest of the document (as opposed to having it in a separate pop-up dialogue) and so that clicking the help icon toggles the help text visibility (possibly with some animation a la fieldset or similar). Either way and anyway, I think that we should aim to simplify the UI by hiding help text and denoting its existence by icons that toggle visibility.

[klonos]

If you have strong feelings about getting the help text as close to the label of the fields...

...never mind this particular comment of mine. After careful consideration, I think that it is best to have the help text between the label and the actual input elements in general (which is what this issue was filed for). Especially if one considers as an example use case a set of many checkboxes or radios. Having the help text after the input elements in such cases actually places it far from the eye of the user (and most likely out of the view port in smaller screens) which constitutes a major UI fail.

I'll file a separate issue for my proposal to hide help text behind a help icon.

[klonos]

And since having the help text below the field is a long-standing drupal standard, we should probably not change it on a whim.

...the overlay has been with us for quite a long time and can be considered a long-standing drupal standard UI-wise. I'm not sure you'll find a lot of people to say that it was a good thing though 😉

[docwilmot]

Perhaps we should also look at what Wordpress...

@klonos: #1388 😁

Also, our version sucks, whether its an established standard or not, it is poor UX. Was writing more but @klonos just intercepted my exact thoughts with that last post including the separate issue. So, ditto.

[klonos]

...whether its an established standard or not, it is poor UX.

@docwilmot ...seems we were thinking the same thing at the same time.

[klonos]

...double ditto 😄

[Graham-72]

Thanks guys. You have made me happy!

I'll file a separate issue for my proposal to hide help text behind a help icon.

I will add ot to my personal to-do list for 2016 - unless someone else gets there first.

[sutibun]

@klonos Nice. You widened the discussion with alternatives. Monkey was focusing too much on help text and only help text.

Perhaps as a veteran I get a bit selfish and tent to ignore the needs of people trying to learn Drupal/Backdrop in favor of getting things faster and having a cleaner UI.

Monkey, the champion of the new user ^_^

Anyway, the help text doesn't bother me even after I know how to use a page. But maybe others are different.

If it's a big issue, how about the following:

• By default, Bd should show the inline help text after the title/label. This is to help newcomers and less advanced users.
• Experienced users who no longer have a need for the help text can optionally go to a settings page and check off "Collapse all help text" which will remove the help text and replace with that question mark button.

[klonos]

I think that this implementation here would greatly improve the UX, but unfortunately not when on mobile. Please see the screenshot I've posted in #1414 (comment) that shows that the clutter and need for long scrolling is there even after moving the help text between the label and the input. I strongly believe that after implementing this thing here, we should also implement #1414 and have it switch to that by default when we hit a mobile breakpoint.

[sutibun]

Didn't think about mobile. Good digging. Hmm... will have to agree then. So, how about we have this on the config page:

How would you like to display the help text?

• Default: Show help text between the label and the input form. However, display a question mark button instead for small screens. (Recommended)
• Collapsed: Instead of displaying help text, replace with a question mark button. Helps to reduce screen clutter.
• None: Do not display any help text on the admin pages. Useful if you're no longer a beginner and know your way around Backdrop.

[jenlampton]

One thing I'd like to differentiate is when the help text is on a text field :

vs when it's on radios or checkboxes:

I think for text fields it's fine where it is, since underneath the test field is not very "far" from the problem. However when we are talking about checkboxes and radios, putting the description text underneath what could be a long list of options is certainly too "far" from the label.

Additionally, I've heard that putting the text way down there below radios/checkboxes is a uniquely Drupal problem (as in, no one else does that). I've been staring at Drupal for so long now that I can't remember it being anywhere else. Do we have any other examples of radios or checkboxes from around the web?

I would be happy to introduce a change that cleans up our radios & checkboxes asap, and then we can continue to debate tooltips hover states and mobile interfaces :)

I also dislike the idea of asking a user where they want their help text. That's not a setting most people would even think about, so let's just try to get it right for them in core, without a UI :) Anyone who wants to change it can use a contrib module.

[Graham-72]

I think that is an excellent way forward. Thank you.
Here is an example from my online banking account which shows a mixture including tooltips.

[jenlampton]

I also like the description text above for textareas (which can also be large)

[Graham-72]

Long description

Yes please!

[docwilmot]

I am in support of moving it to just below the label for all fields, for consistency.

[herbdool]

@stpaultim I've edited the title. It's configurable via the API (with a new #description_display setting) but not in the UI.

[herbdool]

@stpaultim I think your comment about image field's default vs custom help text is a separate issue. It would require some other solution than what is proposed here, which deals with #description regardless of what the source is.

[stpaultim]

I've marked this WFM.

Does someone want to be the advocate for this issue, so we can add it to the milestone.

https://docs.backdropcms.org/documentation/adding-milestones-to-issues

Minor release milestones
In order for an issue to remain tagged for the next minor release, it must meet all of the criteria below:

• It must have been tagged with the milestone candidate - minor label.
• It must have an advocate* (preferably, you!).
• The advocate for this issue cannot also be the advocate for another open issue in this milestone, unless, of course, the other issue has a Pull Request in a near-ready state with either of the labels pr - ready to be committed or pr - works for me.

Or do a code review and mark it RTBC. Any issue that is WFM and RTBC can be added to the milestone.

There is one exception to the above for minor release milestones:

• If an issue has an accompanying Pull Request in a near-ready state that has earned either of the labels pr - ready to be committed or pr - works for me, but is not suitable for a bug-fix release, this issue can also be added to the next minor release milestone.

[herbdool]

I was away from my desk for a few days. I'll advocate, but looks like it'll have to be for 1.30 at this point. @stpaultim

[quicksketch]

This looks really good @herbdool! I reviewed it and only found a few very minor things. Review in the PR: backdrop/backdrop#4798 (review)

Although fieldsets include descriptions, I had to confirm that #type = details does not. So no further changes needed there.

[herbdool]

@quicksketch ready for another review.

[quicksketch]

Looks good to me!

[quicksketch]

Wow, opened for nearly 10 years. Thank you everyone for adding to the discussion along the way. I've merged backdrop/backdrop#4798 into 1.x for 1.30.0.

Lots of thanks to go around on this one. Of course @herbdool for bringing it to code and filing the PR, great work as always. Thank you @klonos, @stpaultim, and @olafgrabienski for testing (and earlier feedback). And thank you to our brainstormers @Graham-72, @jenlampton, @sutibun, @oadaeh, @klonos (again) and @docwilmot.