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.

[acharraggi]

Hmm, so I tried building the PDF locally it also fails, which is good as I can try fixing locally from now on. But the messages makes no sense because all I've done is add content. I do see this mention of "badness" 10000, and a "perhaps a missing /item" but this is near the end of the doc page 880.

I do see that the description paragraph under the square field image is absent in the PDF. So something is wrong, but it shows up fine in the HTML.

still investigating.

[880]
Chapter 30.

Underfull \hbox (badness 10000) in paragraph at lines 46887--46895

 []

(./ftcdocs.ind

Package fancyhdr Warning: \headheight is too small (12.0pt): 
(fancyhdr)                Make it at least 37.03831pt, for example:
(fancyhdr)                \setlength{\headheight}{37.03831pt}.
(fancyhdr)                You might also make \topmargin smaller to compensate:

(fancyhdr)                \addtolength{\topmargin}{-25.03831pt}.

[881

]

! LaTeX Error: Something's wrong--perhaps a missing \item.

[Ethan-goBILDA]

I am very late to the party, but I know I have referenced this page a bunch over the last little while and the current images never quite scratched the itch for me. I took a few minutes and worked up a couple of new images that could live on this page.

Certainly do not feel obliged to use them, perfection is the enemy of progress, and I really appreciate the effort to improve this page! And I understand there are some changes that would be driven by using these new images.

Please let me know if you have any requested changes, or if there's anything else I can do to help here!

[acharraggi]

Ethan, looks interesting. Getting the INTO THE DEEP field on this page would be great since we're updating content anyway (assuming I can fix the PDF gen issue). I don't mind updating the text to match the game.

One issue I have with both images is that the Axes don't appear to meet at the Origin (they seem to float above it). The old images make it clear the three Axes meet at the Origin point. Can you move the axes down a bit so it looks like they meet at the surface of the field in the center?

I do have a problem with the RES-Q image because it's been flipped. The axes point in the right directions, but we're looking at the field from the rear. Ideally both images should have the same orientation, and I think it needs to be from the audience perspective to avoid confusion. The competition manual and field setup both refer to the field from the audience perspective. Can we get this image from the audience perspective?

With those changes I'd be happy to include them.
Thanks.

[acharraggi]

So the PDF gen problem appears to be the ..glossary directive. I removed that from this page. Probably for the best, as I think we're intending to add an actual Glossary page somewhere so we should not need in-page glossaries.

I had capitalized words in the page that were in the Glossary and haven't gone back to change that yet. I do think we'll need a ftcdocs convention about how we want to handle defined terms. In the competition manual they are ALL CAPS, except that is an accessibility problem as screen readers can end up spelling out the letters of the word.

I had hoped to keep the long description in the figure element, but the default alignment for the figure text is centered in a PDF which didn't look good. If I specify :align: left, the HTML looks ok, but the PDF page ends up floating the elements and making a mess. So the long descriptions are in a paragraph that follows the figure. That's should be fine.

I converted the PR to draft so more time to review, plus adding allow time to add Ethan's new images if that works for everyone.

[gearsincorg]

Having one more up-to-date image is cerainly usefull, but I'm not sure they bring any more clarity to the discussion.

If they are used, I'd request that the viewing angle be brought down on the res-q field one, because my brain has trouble with the weird mountain angels from high above. Also can we have the "Alliance station" text inside the boxes in both images?

I also agree that the axis markers need to be brought down so they clearly are at field surface level.

And if FIRST will swear to never use the diamond layout again, we could eliminate the second image all-together :) Just kidding ...

[Ethan-goBILDA]

Here's another pass that implements that feedback. I do agree with Phill that this doesn't likely bring any clarity to that page. So no hard feelings if the best path is to continue with the current images!

[gearsincorg]

Yeah, that's much better. Thanks.

The original images came straight out of the game manual, so we didn't have any flexibility in orientation.

The audience view is the one that most folks are used to,
but... I will say that a view FROM the red alliance station perspective might help to reinforce the X/Y axis orientation definition... Just saying'

[acharraggi]

Revised with new images thanks to Ethan. Also latest commits elsewhere.

Revised how long image description are handled. The long description now goes inside the ..figure directive as a figure "legend" so that the long description becomes part of the HTML figcaption element which is better for screen reader accessibility.