New section for release notes: Accessibility

Development
1

Good morning!
After a discussion we had on the chat yesterday, it appeared that reporting the progress on accessibility in XWiki could be interesting for users.

Here is a proposal for a new section we could add while active work is done on accessibility. Since most accessibility are not backported to LTS, I think keeping this section to latest releases only would be better. Once the work on accessibility gets sparser, this section could be reduced to a minimal version or removed.

I think it would make sense to add this section after the security issues section and before the known issues one.

AccessibilitySecitonRN
AccessibilitySecitonRN911×786 73 KB

In this section we would:

  • explain the current process of WCAG validation in XWiki
  • give a couple of figures to get an idea on the status of this process
  • Link to a widget on the Jira to highlight long term evolution of accessibility

Here is a example of such a section:

Accessibility:
Since XWiki 15.2, XWiki has started a process to improve its accessibility and eventually reach the level AA of WCAG 2.1. The first step of this process was to run automatic accessibility tests. Since then, the community has worked on reducing the amount of accessibility warnings reported by these tests.
As of this release, there is still 671 warnings left in the tests. For reference, the amount of warnings in the last release was 780.
Accessibility violations related to these warnings are reported on the xwiki-platform jira and available at this filter result table.
The progress of accessibility in xwiki-platform through time can be seen on this chart.

Here is a prototype for a template to use for latest releases, with description of the two fields (similar to the example above).

Accessibility:
Since XWiki 15.2, XWiki has started a process to improve its accessibility and eventually reach the level AA of WCAG 2.1. The first step of this process was to run automatic accessibility tests. Since then, the community has worked on reducing the amount of accessibility warnings reported by these tests.
As of this release, there is still <1> warnings left in the tests. For reference, the amount of warnings in the last release was <2>.
Accessibility violations related to these warnings are reported on the xwiki-platform jira and available at this filter result table.
The progress of accessibility in xwiki-platform through time can be seen on this chart.

<1>: Current amount of accessibility warnings in the CI tests. Follow the first section on this documentation page to get this number.
<2>: Previous amount of accessibility warnings in the CI tests. Get them from the last Release notes.

What do you think of adding an accessibility section to the release notes?
Do you think the different points I proposed to include in this section are relevant?
Is the prototype formulation of those different points appropriate for release notes?

I’m looking forward to your feedback!

Lucas Charpentier

2

Sounds good.

Sounds good thanks. Possibly a bit of work to get the 2 numbers but I’m fine since you’re the one doing it ATM :slight_smile:

Sounds very good to me!

Our usual strategy is that if there’s nothing to say in a given release then the section is removed. We do that for a few other sections already.

Thanks

1 Like
3

Looks good. My only comment is that the first paragraph of the section is a bit long and can probably be shortened by removing the non essential background explanations.
e.g.:

We are working towards WCAG 2.1 level AA . Below you’ll find the evolution of the number of warnings found by our automated tests since the last release.

PS: I think we also need to start another discussion for a strategy to not introduce to accessibility issues with each new development.

4

We have the automated tests for that but it’s true that they don’t cover 100% of the WCAG requirements.

5

Sounds good to me, the first part was a bit clunky and not straight to the point :+1:
I think I’ll just make the link point to a less technical page like Understanding the Web Content Accessibility Guidelines - Accessibility | MDN. Trying to figure out what WCAG is from reading the recommendation content is quite difficult.

Updated proposed template:

Accessibility:
We are working towards WCAG 2.1 level AA . Below you’ll find the evolution of the number of warnings found by our automated tests since the last release.
As of this release, there is still <1> warnings left in the tests. The amount of warnings in the last release was <2>.
Accessibility violations related to these warnings are reported on the xwiki-platform jira and available at this filter result table.
The progress of accessibility in xwiki-platform through time can be seen on this chart.

<1>: Current amount of accessibility warnings in the CI tests. Follow the first section on this documentation page to get this number.
<2>: Previous amount of accessibility warnings in the CI tests. Get them from the last Release notes.

Currently there’s still a few rules where fails are introduced pretty often (especially the not-underlined link one, it pops out on a lot of pages). Once we solve those and ‘finish’ the process, any automatic test failure should fail the build and need to be solved. It’s already the case for most of them, but ‘uncommon’ accessibility violations don’t happen too often :slight_smile:

To go further than the automatic tests and build fails, we could add a couple coding styles to avoid bad practices. However we can’t cover everything in code styles (it’d be the same as just saying ‘follow WCAG’, which is way too much constraints in a single line), so the best solution would be to talk about accessibility and make sure everyone designing a new interface is aware of the implications for disabled users. => Raise the awareness of accessibility considerations.

It’s not an easy task and there’s no ‘perfect solution’. So far it seems to me like XWiki platform devs are pretty aware of accessibility questions so I don’t think it’s a priority for now.

6

Well, we already agreed that we should list the best practices as you find them out, in our coding styles. See https://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle/XhtmlCssCodeStyle/#HWCAG where there’s already one best practice listed.

@CharpentierLucas don’t forget to propose new ones to add, based on what you see/fix.

1 Like
7

Maybe I’m a bit out of the focus. But I think it could be worth to have the (most important) a11y improvements in an „accessibility“ sub list inside „new and notewothy for users“?

Simpel

8

Yes, that’s what we will try to do by redirecting to the list of WCAG issues fixed. Manually curating a list is more work and we spend already a lot of time on trying to have nice release notes. It’s always a question of pros vs the cost.

1 Like
9

Updated release notes for XWiki 15.8-rc1. The exact content is similar to what was proposed here, updated with the new statistics added to the artefacts with this commit.