Cms: Improve/suggest field instructions text

[missmatsuko]

Description

Some fields have options that limit allowed inputs, which ought to be detailed in the field's description. For example, it's possible to set a max value on number fields. Currently, it's up to the developer to update the field's instructions to inform the content author of this constraint. If this information is not included in the instructions text, the constraint can really only be determined by just trying an input value and seeing if it saves or not.

I think in C4 we should probably automatically generate instructions based on field options like this, and append it to whatever instructions the developer has (including nothing).

Another option would be pre-populating the instructions settings field with this info, which would allow the developer to tweak it as needed. But then it wouldn't be synced with with changes to the field options, and the developer could remove it entirely (hopefully they don't).

Of course we could always leave it as-is, totally up to developers. I feel like this will be worse for accessibility and usability overall, though. It also wouldn't be super in-line with ATAG, but it may be sufficient to include information on this in documentation, and maybe adding a link to that from the instructions field.

For C3, I'm not sure what the best action would be. If we automatically generate and append instructions, there could be duplicated instructions in the case the developer has already saved good instructions.

[brandonkelly]

I think ultimately developers should be in control and our place is to guide them in writing good instructions – perhaps right from the Instructions field setting, and/or within the docs.

Thoughts @mattstein?

[mattstein]

I think the best solution wouldn’t penalize developers that take the time to write thoughtful field instructions, which might succinctly describe input constraints and the form ideal content should take editorially. Auto-generating and appending seems forcefully opinionated where Craft tends to be a blank slate ready with support for doing the right thing.

What if there were variables available to field instructions that could include the field’s settings and input constraints? It could work as a 3.x feature, continue to give the developer full control, and reduce the burden of keeping the instructions up to date.

So you’d save instructions like...

• Enter a number of rabbits between {min} and {max}.
• Select an uncomfortable photo **at least {transformHandle.width}×{transformHandle.height}**.
• Use {minBlocks}–{maxBlocks} blocks to build the main content of this breathless rant.

Rather than pre-populate empty instructions, you could suggest the same instructions—using the placeholders—with some bit of UI for explicitly using them. Similar experience to the auto-suggested aliases, templates, and environment variables. This could demonstrate how to _use_ the feature, the instructions could still be further tailored before saving, and it’d give the lazy developer an easy way to do the right thing without taking away the choice.

Otherwise maybe written field _input_ instructions could be separate from _editorial_ instructions? Two separate fields, with the former pre-populated by default. Seems more dicey because it would introduce more visual complexity and it’d be a shame if developers avoided displaying instructions for purely aesthetic reasons.

Either way, I’d love to draft _The Art of Writing Field Instructions_ as a KB article and encourage developers to think carefully about it.

My only other idea is wild scope creep and should probably be a plugin. Report on site architecture in a utility: number of sites, sections, entries, fields, etc. In sizing up the site, identify low-hanging opportunities to improve AX and DX, like pruning unused fields, adding field instructions where they’re missing (noting input constraints for accessibility), etc. Each opportunity could be linked to supporting explanation in the docs or knowledge base.

[missmatsuko]

@mattstein Nice, I like the idea of having variables in there so changes to the constraints will update the instructions text accordingly.

Rather than pre-populate empty instructions, you could suggest the same instructions—using the placeholders—with some bit of UI for explicitly using them. Similar experience to the auto-suggested aliases, templates, and environment variables. This could demonstrate how to use the feature, the instructions could still be further tailored before saving, and it’d give the lazy developer an easy way to do the right thing without taking away the choice.

This sounds good to me also!