Document accessibility features in Image

This proposal does not fit with the structure of the hook_help() "About" and "Uses".

Probably this is a "uses" item, since the ATAG guidelines you cite say we should be documenting how content authors can either use accessibility features in the authoring UI, or how any author (with or without limitations in how they use the UI themselves) can set up content to be accessible.

So I think what we need to do is add a new "uses" item... these should start with an -ing verb. How about this:

Configuring image fields for accessibility

For accessibility, all images displayed on web sites should have alternate text; they may also have title text. Image fields can be configured to either allow or require alternate and title text, in the field settings; requiring alternate text is one way of ensuring that all images have alternate text to display. The default image formatter will output any provided alternate and title text in the HTML img tag.

Thoughts?

Also note that the image module help needs an update in general. See
#2091337: Update hook_help for Image module
This issue should probably either be postponed until the other one is done, or incorporated.

Yes, it has to do with the standards we've adopted for hook_help(), not hook_help() itself.

If we come up with a module where having a whole new section for Accessibility makes sense, then we can reconsider the standards, but adoption of new coding/docs standards is a very difficult process in the Drupal community. So unless you really have things that fall outside of "About" and "Uses", it would be best to stick with our current standard.

Anyway... of course go ahead and add the text above to any d.o page that it needs to go on.

This looks pretty good, but I'm now confused about whether you are recommending just alt or if using an alt and title both is OK?

OK, maybe this can be rewritten a bit to stress this then? Also "who" referring to screen readers is a bit weird in that sentence; should be "which" and preceded by a comma.

Oops -- dd tag in there twice:

'<dd>' . t('<dd>

I also think this can be written more efficiently. How about this:

For accessibility and search engine optimization, all images that convey meaning on web sites should have alternate text. Drupal also allows entry of title text for images, but it can lead to confusion for screen reader users and its use is not recommended. Image fields can be configured to either allow or require alternate and title text, in the field settings; the recommended settings is to require alternate text and disallow title text.

Should be "... recommended setting is to ..." not settings? Also, we should use the same terminology (enable/disable, or allow/disallow) that is used in the UI for these settings. Have you looked at that and made sure they match?

OK, we're nearly there!

So... "to either allow or require alternate and title text" implies that there are two choices: (a) allow and (b) require, whereas there is actually a third choice, (c) do not allow at all.

Also, I checked in the UI. The settings for whether the alt/title are even allowed are called "Enable ... field" and the settings for whether they are required are called "... field required".

So here is a proposed rewrite of the last sentence:

Image fields can be configured so that alternate and title text fields are enabled or disabled; if enabled, the fields can be set to be required. The recommended setting is to enable and require alternate text and disable title text.

I also think that this information should be added to the field settings form itself. This is in
\Drupal\image\Plugin\Field\FieldType\ImageItem::fieldSettingsForm().
Having it in the hook_help() is OK, but this information will not necessarily be getting to people who are actually setting up fields.

This is looking good!

A few details to take care of:
a)

      $output .= '</dl>';
+      $output .= '<dt>' . t('Configuring image fields for accessibility') . '</dt>';
+      $output .= '<dd>' . t('For accessibility and search engine optimization, all images that convey meaning on web sites should have alternate text. Drupal also allows entry of title text for images, but it can lead to confusion for screen reader users and its use is not recommended. Image fields can be configured so that alternate and title text fields are enabled or disabled; if enabled, the fields can be set to be required. The recommended setting is to enable and require alternate text and disable title text.') . '</dd>';
+      $output .= '</dl>';

There are two </dl> tags now. oops.

b) You've misspelled recommended in several places in the UI updates as "reccomended".

OK, it all looks good now... hm. One last thing I noticed (sorry for not noticing it earlier). The two "alt" fields have descriptions like "It is recommended to ...", while the "title" field says "Enabling this field is not recommended...". We should probably make them more parallel; I think I prefer the "title" wording? So we could say "Enabling this field is recommended" and "Making this field required is recommended" for the alt fields? Thoughts?

OK, seems like we're both happy with the text now. Thanks for all the patches!

Thanks!

Click "View" to see the results, and expand one of the items. There's some kind of problem with the test bots. They're running out of PDO database connections. Try again in a few hours, maybe it will be fixed?

Committed af221c8 and pushed to 8.0.x. Thanks!