Suggested changes for Pattern 4.2.5 Clearly Identify Controls and Their Use

[SteveALee]

As described in #154 there are a range of changes I'd like to see made to the patterns

I've worked in detail on Pattern 4.2.5 Clearly Identify Controls and Their Use by making comments in a google doc. I've also provides an example updated pattern. The diffs are hard to read but I could transfer to the Google Doc if that helps.

See #154 (comment) for a summary of this thread

[julierawe]

It's great that the updated pattern you're suggesting has a shorter "How It Helps" section (4 paragraphs is less daunting than the previous version's 7 paragraphs), but what is the logic is for splitting the "how to do it" details into two non-consecutive sections: 4.2.5.2 What to Do and 4.2.5.4 More details?

Also, the 1st sentence in "What to do" could be more direct. Suggest changing "Ensure interactive controls that do something, including links, can be clearly distinguished from non-interactive elements." to "Clearly distinguish interactive controls, including links, from non-interactive elements."

[SteveALee]

Thank you

what is the logic is for splitting the "how to do it" details into two non-consecutive sections: 4.2.5.2 What to Do and 4.2.5.4 More details?

That's not actually a change in this suggestion. The original intention was that the 'boring details' would be in More Details.

I felt the "Description" section should be renamed to 'What to Do' to focus on being a high level description of the approach to take. More Details (suitably renamed - #151) then describes the actually techniques to apply.

I do agree having them non consuctive is poor structure. I also feel the title 'More Details' is confusing as it could also apply to 'How It helps, especially giving the interleaving of sections as you highlight. Do you think making More Details would better be a subsection of What to Do? We do then hit issues with section numbering being long and fomating of deep section levels is a bit messy in TR Notes.

Also, the 1st sentence in "What to do" could be more direct.

Thank you. I definitely think directness is very important here!

[julierawe]

I think it would be great to combine "What to do" and "More details" into one section--especially since the "boring details" are essential for helping users understand how to do it. If the "how to do" it details lean heavily on bullet points, then the combined section won't feel too onerous/hard to read/digest.

One other streamlining section: Instead of separating "Getting started" into its own section, consider making it the last paragraph in the "What to do" section. See below.

If you make these changes, then the updated structure would be:
Pattern
1. User need
2. What to do
—1st paragraph: 1-2 sentences, with 1st sentence always starting with action verb
—2nd paragraph: "This can be achieved by:" followed by bulleted list of specifics
—3rd paragraph: "To get started," followed by short, very specific tip
3. How it helps: I suggest aiming for a maximum of 4 short paragraphs--when you get longer than that, people start to skim TLDR :)
4. Examples: Is the goal to include only 1 "Use" and 1 "Avoid" in every pattern? Or maybe 2 for each, whenever possible?
5. Related patterns: I suggest coming up with a maximum number of patterns to include in this section or else it could get overwhelming/skipped over if it starts getting too long. The fewer patterns you include here, the more likely people are to pay attention to them.
6. Related WCAG SCs

[SteveALee]

We're definitely on the same page here Julie! And it's excellent to have my "spidey sense" backed up with solid editorial experience. :)

especially since the "boring details" are essential for helping users understand how to do it

That's a good point!

consider making it the last paragraph in the "What to do" section

This streamlining does get over a concern I have with three sections - which one should someone pay the most attention too. I thought this was a good example of a getting started paragraph:

Plan the design for your information before adding content. Think about the colors, font choices and areas where text and images will appear.

Examples: Is the goal to include only 1 "Use" and 1 "Avoid" in every pattern? Or maybe 2 for each, whenever possible?

Ideally, 2 of each

suggest coming up with a maximum number of patterns to include in this section

I was trying to come up with and describe a heuristic for this. "Only Patterns in other Objectives" will miss some important ones. So I'd say we aim for only those that are closely related. Three or four at the most feels like a good limit.

FYI for the intended Interactive Web version of the design guide these Related sections could be in an aside - like the side bar in this possible layout

[julierawe]

Ooh, side bar = exciting!

My Understood colleagues and I think it's likely that many users will read the entire COGA guidelines from start to finish (rather than hunting for something specific). There is so much great information in these guidelines that will be new to so many folks, and everything you're doing to chunk it out, make it easier to digest, is terrific.

I still have a few more comments to submit about other parts of the guidelines, but am happy to be a sounding board as you're debating different solutions, cheers!

[SteveALee]

My Understood colleagues and I think it's likely that many users will read the entire COGA guidelines from start to finish (rather than hunting for something specific).

That is a really interesting to hear. We currently think there are 2 types of users - those like you describe who are explicitly interested in cognitive accessibility and designer / developers who want to do whatever is required to meet accessibility. Different audience different formats? Does that imply an interactive searchable/browsable web version should also have a sequential access mode?

Please do add more and thanks for the offer!

[lseeman]

please stop using issues for internal discussions. A lot of the members find them hard to track.

[SteveALee]

@lisa - this is an 'external' public discussion for now, prior to internal discussion. Many people prefer github issue discussion when they bring comments and suggestions and I think think we should engage with them.

I'm expecting to bring a summary to another channel soon. But which is best? One to put on our agenda.

[SteveALee]

See #154 (comment) for a summary of this thread

[lseeman]

Steve can u close this?

[SteveALee]

Closing as requested and dealth with