In T185752#4275588, @Esanders wrote:

I also think the order is not right for align:top, the field should come immediately after the label in read order, that is already the case in align:left as you scan right from the label, but not in align top, where it goes label>help>field.

In this example the large disconnect between label and field makes it really hard to parse:

,

much better whould be:

In T185752#4275596, @Volker_E wrote:

That's a though one, I'm not completely convinced about below being clearer. What the new 'helpInline' exposes much clearer as issue: label texts, even secondary should be short and dense.

In T185752#4275634, @Esanders wrote:

The help should be additional information the user can read should they be having trouble using the form using just the primary labels. Wedging it middle of the normal read flow forces them to scan it before getting on to the field. It's auxiliary information and should be presented as such.

In T185752#4275638, @Volker_E wrote:

But the proposed treatment would still break the flow, eyes moving down, then up again, then down.
Exactly what we intended to resolve with this possibility. If there's too much text, one can stick to the help PopupButtonWidget.

In T185752#4275642, @Esanders wrote:

But the proposed treatment would still break the flow, eyes moving down, then up again, then down.

The primary use case is that user figures out how to use the form from the label and the field alone. If after reading those they are still stuck, they advance to the help text, then return the finish filling in the field. In the primary case the fill out the field, then scan down to the next field heading.

The first layout would only be better if we assumed the user would mostly likely have to read the help text to fill out the form, but that shouldn't be the case.

Another example:

The enable/disable are closer to the next label in the form than their own label.

Change 439919 had a related patch set uploaded (by Esanders; owner: Esanders):
[oojs/ui@master] FieldLayout inline help: Move help after field when align=top

https://gerrit.wikimedia.org/r/439919

I agree with having an issue in F22145141, but that is more so a problem with the too small top margin of the PanelLayouts

Agreed - although even with some top margins on the headings, the fields are still way to far from their labels.

I agree with Ed, this seems like a good idea. The help text (whether shown in the popup or inline) is supposed to be an additional explanation, and in most cases users should not have to read it before they can fill in the field. It makes sense to put it underneath, to keep the main label and field closer together.

We need to find more examples before making that the default output of the library.

Both, @RHo & @alexhollender provided good feedback on the different use cases for above and below. Alex also shared, that we need to think about how error messages would play into either.

Our existing notices system, which we will want to replace with this (T197179), currently places the messages below the field.

In T185752#4275638, @Volker_E wrote:

If there's too much text, one can stick to the help PopupButtonWidget.

As mentioned in a comment on T185752:

In T185752#4220086, @Prtksxna wrote:

Some times the help text is very long, but essential for the user to not make a mistake, so must be inline and not be hidden behind an icon, at other times it's small but not important…

I agree with @Esanders too, and would like to know more about the feedback provided by @RHo and @alexhollender. @Volker_E, could you share more, or a link to general notes?

In T197004#4280018, @matmarex wrote (emphasis by myself):

I agree with Ed, this seems like a good idea. The help text (whether shown in the popup or inline) is supposed to be an additional explanation, and in most cases users should not have to read it before they can fill in the field. It makes sense to put it underneath, to keep the main label and field closer together.

Where does this assumption come from? Is this anywhere explained or did we follow this “unwritten” guideline ourselves throughout our projects?

In T197004#4314770, @Volker_E wrote:

In T197004#4280018, @matmarex wrote (emphasis by myself):

I agree with Ed, this seems like a good idea. The help text (whether shown in the popup or inline) is supposed to be an additional explanation, and in most cases users should not have to read it before they can fill in the field. It makes sense to put it underneath, to keep the main label and field closer together.

Where does this assumption come from? Is this anywhere explained or did we follow this “unwritten” guideline ourselves throughout our projects?

Looking at Special:Preferences we see three examples of help text in Internationalization, Signature, and Email options. In all of these, a person is able to fill out their preferences just by reading the label — "Email", "Signature", "How do you prefer to be described?". Reading the help text is not needed. No harm is done if they aren't read, and the results of changing a preference are exactly what a person might expect.

For those who need to know more about how this information is going to be used the extra text is helpful. Even for them its unlikely that they need to read it every time before they edit the field.

In T197004#4314770, @Volker_E wrote:

In T197004#4280018, @matmarex wrote (emphasis by myself):

I agree with Ed, this seems like a good idea. The help text (whether shown in the popup or inline) is supposed to be an additional explanation, and in most cases users should not have to read it before they can fill in the field. It makes sense to put it underneath, to keep the main label and field closer together.

Where does this assumption come from? Is this anywhere explained or did we follow this “unwritten” guideline ourselves throughout our projects?

Hmm, it is a guideline I've always personally followed when deciding whether some text should be a label (always shown) or a tooltip (shown on hover/click). I don't actually know if it's generally accepted, perhaps I should have spoken less authoritatively :)

I found another case where we've already used additional labels underneath the field, in the cross-wiki upload dialog (in VE, Insert → Media → Upload):

(The CSS class for them is mw-foreignStructuredUploa-bookletLayout-small-notice, and yeah, that's a typo in it ;) )

The task for this was T116086, there is some discussion in it.

In an example to the contrary, the new design for UploadWizard (https://commons.wikimedia.beta.wmflabs.org/wiki/Special:UploadWizard) places additional labels above the field:

(Ignore the misplaced "Remove" button, I just submitted a patch to fix it.)

The task for this was T197924, I don't see any discussion there, but there might be some rationale in the private Zeplin project linked there, which I can't access.

Change 439919 merged by jenkins-bot:
[oojs/ui@master] FieldLayout inline help: Move help after field when align=top

https://gerrit.wikimedia.org/r/439919

Change 452872 had a related patch set uploaded (by VolkerE; owner: VolkerE):
[mediawiki/core@master] Update OOUI to v0.28.0

https://gerrit.wikimedia.org/r/452872

Repeating myself from patch set comment:
@RHo brought up at another design discussion, that Material design is positioning assistive text besides the label as positioned below. https://material.io/design/components/text-fields.html#anatomy
I'm still not fully convinced by this, but am ok to follow in order to move this forward. We should be outspoken and limiting when we're using and promoting such uses!

Update: I've changed the description in the demos to be verbose on optional, assistive character of inlined help (for now).

Change 452872 merged by jenkins-bot:
[mediawiki/core@master] Update OOUI to v0.28.0

https://gerrit.wikimedia.org/r/452872

The OOUI release landed in MediaWiki 1.32.0-wmf.18.