Currently, in the Documentation Guide, there is already a rule that hasn’t really been followed:
“You should add a piece of text in italics under images that describes what that image is about (by using the caption parameter of the image macro).”
So, if we decide to enforce captions, the implementation could rely on the caption parameter of the image macro.
The pros of having them are:
They improve SEO and accessibility.
The cons:
They might make the documentation harder to write and contribute to.
It’s possible that developers might avoid using images if there are too many rules, so globally it wouldn’t necessarily be an improvement for the documentation.
Having too many rules makes things harder to follow. Ideally, we should support them with automation checks and work on a “documentation guide” XWiki application for xwiki.org, to verify and enforce the maximum number of rules from the documentation guide automatically.
How do you propose to implement captions for Tables?
With the {{figure}} and {{figureCaption}} macros?
My POV is that it’s too much work to have them and they’re more suited for a book than a website. There’s already a lot to do on other topics and I fear that we’re going to make it hard or impossible for anyone to contribute. Now, we might be passed this point already as the doc guide is beefing up every day, so we could also go all-in. If we want to have captions, then I’d suggest to make the rendering fail if they’re not present or on page save.
Generally speaking, I believe we should have an Event Listener on page save that validate the doc guide as much as possible.
It’s either with the {{figure}} and {{figureCaption}} macros indeed, or by using a summary attribute (% summary="" %). The difference between the two is that the {{figure}} macro displays the caption directly in the page content, so it’s accessible to screen readers and search engines, and visible to readers. The summary attribute is mostly for accessibility (and is a bit deprecated), but not visible to readers.
This rule contains the verb should and not must, so as far as I understand it’s technically correct to not apply it.
I agree that enforcing captions everywhere will make it even harder to contribute to documentation. I like the way it is now, a recommendation but not an obligation, and I don’t think we need to change this rule strictness.
I’m -0 on this, I personally wouldn’t mind enforcing it but I doubt it’d be a good compromise to make at the community level: potential doc contributions VS doc quality improvements.
We should definitely improve how we handle should rules though.
Side reference: Here’s the HTML and CSS guidelines, which has a similar MUST/SHOULD distinction. Because it’s a critical property of every rule and can change completely how people view/apply a rule, we (the guideline editors) organized the guidelines around the levels of priority.
+1 from me on this idea
It could fail rendering of edits that don’t comply with our documentation rules (MUST), and send warnings for edits that don’t comply with our doc quality best practices (SHOULD). This way, if we handle these warnings properly, we can keep an updated list of quality fixes TODOs on a technical page of our doc wiki. This could make it easier to find concrete improvements to implement on DocFixingDays.
E.g. it’s DFD, I go on the document to check the warnings, filter the imageMissingCaption warning category and start adding caption to doc images where it’s missing.
VS today, if I want to improve the quality of our doc, I start by picking a page to review and scan through its content to check that our rules are followed. In this, old and forgotten docs are never reviewed and brought up to our standard.
The main compromise I see here is:
- time implementing and maintaining this doc validator
+ improving doc consistency and quality
Thanks for starting this brainstorming!
Looking forward to its results
I like the idea. However, it may indeed add too much beaurocracy to images.
My initial thought was to see if the value of the alt attribute could be somehow copied into the figure caption, as I’d imagine every image already has an alt. However, according to this article I’ve found, the alt attribute is not required as long as there’s a caption.
I’ve looked at the Documentation Guide and couldn’t see anything about usage of the alt attribute. What’s the policy around its usage?
If no alts are used, I’m leaning towards adding captions to images. If alts are used, then I think it’s not as much of an issue.
Hi! alt is a HTML attribute that can be used in XWiki Syntax and defines what text is displayed when the browser is not able to display the image. The difference from the caption parameter of the image macro is that the caption provides a visible text shown alongside the image.
BTW I really like @CharpentierLucas 's idea of having “musts” and “shoulds” in the doc. I think this is a case where we have a should.
It’s especially important for accessibility: people that cannot rely on vision will REALLY need this alt to understand what you’re showing. If you’re not adding an alt, you’re ‘hiding’ information from a lot of assistive technology users. Here’s a short example of how alt text will help
Adding captions on all pictures is not always possible because of design (e.g. the XWiki logo in the top left corner of this forum UI would look weird with a caption). An alt is completely invisible in most use cases but it’s a solid fallback in all situations where things don’t work out as expected.
For reference, here is a pretty well written page about image alts:
-0 Same as Lucas, I think we should keep it as it is and only recommend it.
+1 for the Event listener, I think it could also make the contributing guidelines slowly known by contributors, that might not read the guide at first, and progressively learn guidelines and best practices one contribution after the other.
Thanks a lot for clarifying this! I actually thought alt was mainly for cases where the image can’t be loaded (e.g., no internet), and that only captions could address WCAG requirements. Now I understand that alt is very important for accessibility and for people who use assistive tools. Thanks for sharing the interesting video and article!
