Specification Readability

[AlexDawsonUK]

This issue was discussed during a previous IG meeting and is on our list of things to resolve.

Currently, the specification is large and quite dense to read through. While technical documents are fine for like-minded individuals, it's not great for the public to wade through. Some efforts have already been made to improve the readability of the specification such as making the additional material related to guidelines visible on-demand (click-to-reveal) to reduce excessive scrolling (thus condensing over 200 pages!). However, more can be done. Work to improve the language usage within the text to make it easier to read (as one example), and education materials are on the list in another issue.

This issue has been opened to allow anyone to submit ideas for how we could make the spec more reader-friendly, taking note that we are rather restricted in style due to the ReSpec format, but if it's possible, I'll see what magic I can achieve.

[AlexDawsonUK]

Privacy Principles has a role based labeling system that uses progressive disclosure to reduce clutter based on what is relevant to the type of work you will be undertaking. We have an existing tagging system for our JSON API that can be utilized and/or extended to SCs to produce a similar effect thereby improving readability through role-based filtering of the guidelines.

[AlexDawsonUK]

Decide upon the tag labels we wish to apply to such a system if it were to be created:

• Discipline?
• Technology?
• Both?
• Something else?

[AlexDawsonUK]

Proposal: As the descriptions within guidelines are non-normative (can't be actioned upon), the content should be moved to the "additional content" section thus retaining it's status as useful contextual information (the "why"), but leaving "the what" todo (normative) front-and-center and further reducing the document impact on readability.

[kazuhito-kidachi]

We might create several versions of WSG, just like HTML spec of WHATWG has One-Page Version and Multipage Version, if they can be maintained automatically as much as possible. One-Page Version can be useful for in-page search, printing out, etc.

[AlexDawsonUK]

Proposal: As the specification reaches maturity and gets towards note status, the ability to maintain references will become problematic (as the document will reach a static state). As such, extracting the references and placing them in a structured supplement categorised by guideline and SC, highlighting the best material would be healthier for the longevity of the guidelines and will also reduce the size of the main document considerably (as references are a huge proportion).

[kazuhito-kidachi]

As to say about the idea of filtering SCs, we might be able to imitate How to Meet WCAG (Quick Reference). In case of Quick Reference, users can filter SCs of WCAG in various ways, the tool is separated from WCAG itself though.