This issues takes the specific example of issues with our current wording of SC 1.2.1 - 1.2.5, to highlight problems with the structure of our summary and suggest a solution.
Current wording of the summaries for SC 1.2.1 - 1.2.5
What's the problem?
There are a few issues with the above:
Problem 1: Wrong link to SC 1.2.5
The last one ('Audio description') corresponds to WCAG SC 1.2.5, not 1.2.4. (The link needs to be fixed).
Problem 2: Not distinguishing between A- and AA-level requirements is making things harder for readers
It's really what the last two requirements ('Text or audio description' and 'Audio description') mean in the context of each other.
I.e. it looks like, if you meet the 'Audio description', you automatically meet 'Text or audio description', right? So what's the point of listing both?
Well, 'Text or audio description' is required for the A level of compliance, while 'Audio description' is required for the AA level. That's why there's a distinction.
This highlights a problem with our current layout: we are not showing the level of conformance that each requirement corresponds to. Initially I thought that that would be a good sacrifice to make to simplify things. But in this case, it makes things more difficult to understand. And it also means that colleagues don't know where to start, if they don't want to meet the AA-level of conformance.
Problem 3: Unclear distinctions between requirements for 'pre-recorded' and 'live' content
-
It's not clear which requirement is for pre-recorded content, and which is for live content as well.
-
Also, in the WCAG, captions for pre-recorded performances is a A-level requirement, while captions for live performances is a AA-level requirement. The current summaries don't show this distinction. This was intentional, but I'm concerned that, without that distinction between A-level and AA-level requirements, readers might think that these guidelines are hard too hard to get started with.
Suggested solution
Prototypes
-
Prototype A: Table with Requirement first. In the 'overview-layout-test1' branch, I've experimented with a new layout using a table.
-
Prototype B: Table with Level and Responsibility first. In the 'overview-layout-test1b' branch, I've also prototyped a slightly different version, where the 'Level' and 'Responsibility' columns come before the 'Requirement' column.
-
Prototype C: Table with Level and Who first. The 'overview-layout-test1c' branch is the same as Prototype B, except that I've replaced the column header name 'Responsibility' by the word' Who'. I think that 'Who' is slightly less descriptive, but it makes the column narrower, leaving out more width for the requirement column. This makes the requirement easier to read, and takes less lines).
-
Prototype D: Table with Who first, then Requirement and Level last. The 'overview-layout-test1d' branch is the same as Prototype B, except that I've put the 'Who' column first, and the 'Level column' last.
Comments
-
I'm using tables (one for each Guideline, e.g. "Guideline 2.1: Provide alternatives for audio content, videos and presentations"), rather than just lists of bullet points
-
The tables have a column for "Conformance level"
- This is for distinguishing between A- and AA-level requirements
- I suggest that we don't list AAA- level requirements, as they are not used in any standard. Instead, I propose that we use the content from AAA-level requirements in other documents or training workshops, when we provide best practices not covered by the WCAG AA standard.
-
The tables have a column for "Responsibility" (e.g. Design, Content, Engineering)
- This is to make it easier for colleagues to:
- Understand what success criteria they need to understand and focus on
- Not get confused by success criteria that are fully outside what is typically considered their immediate remit, so that they find this document easier to read
-
The tables DO NOT have any other column
I know that it can be tempting to solve other usability issues, or answer other feature requests, by adding new columns. But if we add any other column, our document will become unpleasant to look at and overwhelming. I propose that we stick to 3 (or less) columns maximum.
For example, one issue is that some people don't expect that most of these success criteria apply to native apps. So it can be tempting to add a column that says either "Web" or "Native and Web". I propose that we do not do that, because, unless exception, all of these success criteria apply to native apps. I think that it's better to just call out those exceptions.
-
I'm not yet sure which prototype works best. Probably B or C
Note
Right now we're working with plain Markdown, for two reasons:
- Plain markdown makes it really easy for anyone to quickly update the document, without requiring knowledge of HTML/CSS, and without getting bogged down in code
- The simplicity of plain Markdown forces us to focus and find simple solutions to usability issues / feature requests.
It could be tempting to just say "oh, the document isn't working right now, but we'll ask a designer to design it better and we can use CSS to solve all our problems".
I suggest that instead of doing that, we solve our most important problems using the simplicity of plain Markdown. This avoids feature bloat and procrastination.
But, once the content of this document, and its structure, is stable, yes let's improve its elegance and usability with CSS, for sure.
And once we use CSS, it might be that we stop using a table, and use something like dots or tags to achieve the same structure is a more elegant way.
Next steps
What do you think?