Field Coordinate System page - add image descriptions and other readability fixes

[acharraggi]

This started as an update to the alt tag text. But these are complex images that can't be described in 120-140 characters. So a long description was added prior to each image.

The Alt tag text and the figure captions were re-written to make sense if they were both spoken out loud, or if only the caption was read out loud (some browers/plugins will read the text of a page aloud but not include anything about navigation or images). Since the Figure numbers are not referred to in the text, the "Figure x:" start of the captions was removed. Since we normally caption images, our alt tag text can probably be quite short ,as long it doesn't directly duplicate the caption.

:class: no-scaled-link was added to each figure as there is no need for a link to the image that is already being shown. Those links just make the page more complicated to tab through or to listen to with a screen reader.

In addition there were a number of grammar and punctuation changes made.
Those have been cleaned up, with the intent of making the text more readable both in general and for a screen reader.

Some text and a link to background material replaced "(orthogonal axes)" and the same was done regarding "as one would normally expect from the usual classic 2D geometry".

"FIRST Tech Challenge" was removed from the H1 header (and therefore also from the title) as being extra verbiage that you're force to hear when spoken aloud. That text is in the Title, the breadcrumbs, and the page H1 header. In the context of this being the FTC Docs site we don't need to use "FIRST Tech Challenge" quite so much on some pages.

[WestsideRobotics]

The Alt tag text and the figure captions were re-written to make sense if they were both spoken out loud, or if only the caption was read out loud (some browers/plugins will read the text of a page aloud but not include anything about navigation or images). Since the Figure numbers are not referred to in the text, the "Figure x:" start of the captions was removed. Since we normally caption images, our alt tag text can probably be quite short ,as long it doesn't directly duplicate the caption.

The above suggests that the revised image will have both a caption and alt tag text. But the generated page shows only the separated/orphaned 2nd part of the alt text. Is that intended?

[acharraggi]

Yes, alt tags do not show up visually in your browser normally. You can "inspect" the image, which should show the HTML source of the tag with the alt attribute. The caption text has to make sense by itself. I've got more details in issues 126 and 132 in the private repo. Alt tags are intended to be read aloud, they will show in the browser as a placeholder if you disable image loading. For screen readers for the blind like JAWS, the alt tag text will get read aloud, plus whatever text follows the image, such as the caption. So in that case, the alt text must make sense in context. Note: some browsers/plugins can read a page aloud, but they often skip all navigation and images (including the alt text).

We can't omit the alt tag in the figure otherwise Sphinx puts the path to the image in the alt text. Sphinx wouldn't let me construct an alt=' ' (blank character) tag which is recommended when the image is already described or captioned. And if you omit the caption, then Sphinx jams the next paragraph against the image (which I suppose we could fix with CSS). But we seem to have captioned most images, so I didn't want to change our style.

Most of our figures in ftcdocs have both alt text and captions. My recommendation would be to adjust the wording of both so that they make sense together or separately. And if the image is complex, like the three on this page, then we add a long description in the body of the page. And if read aloud, the alt text should not be a copy of the caption. Given that all three image on this have long descriptions, it was kind of tricky to write alt text and a caption that made sense.

Feel free to suggest different wording. This is somewhat subjective, I think this is my third rewording of alt text and captions before I felt is was ok to publish, and I don't think it's great. To improve accessibility the goal here is to add text descriptions of the images, but I did run into constraints dealing with the RST figure markup.

[acharraggi]

I tried to improve the clarity of the field descriptions plus more readability fixes in the commit today. Such as converting RED WALL to Red Wall and replacing 24 in. x 24 in. with 24 inch by 24 inch to make them better for read aloud processing. Some read aloud plugins will pronounce the individual letters of a CAPITALISED word. I had a problem where I had capitalised all the ALLIANCE words, and just one of those in the entire page was read out as letters despite being spelled the same as all the other words where it was able to say the word, just weird. But I recalled reading about this, that some screen readers don't handle all caps well. Also, since this is a definition page, I added a Glossary for a few key words related to Field Coordinate System.