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.