WebAIM - Web Accessibility In Mind

E-mail List Archives

Thread: resources on writing accessible user guides

for

Number of posts in this thread: 13 (In chronological order)

From: Scott Brackett
Date: Fri, Apr 16 2021 12:27PM
Subject: resources on writing accessible user guides
No previous message | Next message →

Hi all,
I'm looking for additional resources/guidelines about writing better user
guides for websites/web applications, specifically:

- Best practices for navigation description: instead of "click to the
left of X..." I would tend towards using "select X under the Y heading."
What are some other options?
- Should we stop using sight-based idioms like "look" and "see"? Are
those to be avoided in favor of "...find the X link after the Y heading" or
"if you are searching for X, select the Y link under the Z heading...."
Or is that over-thinking it?
- What are recommendations on what interaction descriptor to use instead
of "click?" Are "select" or "choose" good options? Any others?

I really appreciate any help you can provide.
Scott B.

From: Patrick H. Lauke
Date: Fri, Apr 16 2021 2:08PM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

On 16/04/2021 19:27, Scott Brackett wrote:
> - Should we stop using sight-based idioms like "look" and "see"? Are
> those to be avoided in favor of "...find the X link after the Y heading" or
> "if you are searching for X, select the Y link under the Z heading...."
> Or is that over-thinking it?

Anecdotally, having worked with various blind/visually impaired
colleagues and user, words like "look" and "see" aren't really taboo.
Some use them themselves. If there's a better fit for certain
situations, sure. But I wouldn't worry too much about the occasional use
of them.

> - What are recommendations on what interaction descriptor to use instead
> of "click?" Are "select" or "choose" good options? Any others?

Similarly, "click" has become so prevalent that it has a reasonable
"input agnostic" quality to it. If there are more apt ways to describe
an interaction, sure ... "select" when it's actually something that you
select from a list of options or similar. "toggle" when it's a toggle.
"press" a button. "follow the link". "activate". But the occasional
"click" is also fine, particularly if alternatives would start to read
very janky and awkward.

P
--
Patrick H. Lauke

https://www.splintered.co.uk/ | https://github.com/patrickhlauke
https://flickr.com/photos/redux/ | https://www.deviantart.com/redux
twitter: @patrick_h_lauke | skype: patrick_h_lauke

From: Jonathan Avila
Date: Fri, Apr 16 2021 2:59PM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

> Best practices for navigation description: instead of "click to the left of X..." I would tend towards using "select X under the Y heading." What are some other options?

Choose the items below or above is better than left or right -- refer to the understanding document for SC 1.3.3 (https://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-understanding.html). I've still had folks raise issue with after and before - but they are sequential for most mediums.

> - Should we stop using sight-based idioms like "look" and "see"? Are those to be avoided in favor of "...find the X link after the Y heading" or "if you are searching for X, select the Y link under the Z heading...." Or is that over-thinking it?

I typically use other words like locate or refer to, etc.

> - What are recommendations on what interaction descriptor to use instead of "click?" Are "select" or "choose" good options? Any others?

"Choose" is another option

Jonathan

-----Original Message-----
From: WebAIM-Forum < = EMAIL ADDRESS REMOVED = > On Behalf Of Scott Brackett
Sent: Friday, April 16, 2021 2:28 PM
To: WebAIM Discussion List < = EMAIL ADDRESS REMOVED = >
Subject: [WebAIM] resources on writing accessible user guides

CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender and know the content is safe.


Hi all,
I'm looking for additional resources/guidelines about writing better user guides for websites/web applications, specifically:

- Best practices for navigation description: instead of "click to the
left of X..." I would tend towards using "select X under the Y heading."
What are some other options?
- Should we stop using sight-based idioms like "look" and "see"? Are
those to be avoided in favor of "...find the X link after the Y heading" or
"if you are searching for X, select the Y link under the Z heading...."
Or is that over-thinking it?
- What are recommendations on what interaction descriptor to use instead
of "click?" Are "select" or "choose" good options? Any others?

I really appreciate any help you can provide.
Scott B.

From: Scott Brackett
Date: Fri, Apr 16 2021 3:19PM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

Excellent! Thanks Patrick and Jonathan! I'd love to hear more if others
have additional opinions/experiences to offer. These concrete examples are
very helpful.


On Fri, Apr 16, 2021 at 3:59 PM Jonathan Avila < = EMAIL ADDRESS REMOVED = >
wrote:

> > Best practices for navigation description: instead of "click to the
> left of X..." I would tend towards using "select X under the Y heading."
> What are some other options?
>
> Choose the items below or above is better than left or right -- refer to
> the understanding document for SC 1.3.3 (
> https://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-understanding.html).
> I've still had folks raise issue with after and before - but they are
> sequential for most mediums.
>
> > - Should we stop using sight-based idioms like "look" and "see"? Are
> those to be avoided in favor of "...find the X link after the Y heading"
> or "if you are searching for X, select the Y link under the Z
> heading...." Or is that over-thinking it?
>
> I typically use other words like locate or refer to, etc.
>
> > - What are recommendations on what interaction descriptor to use
> instead of "click?" Are "select" or "choose" good options? Any others?
>
> "Choose" is another option
>
> Jonathan
>
> -----Original Message-----
> From: WebAIM-Forum < = EMAIL ADDRESS REMOVED = > On Behalf Of
> Scott Brackett
> Sent: Friday, April 16, 2021 2:28 PM
> To: WebAIM Discussion List < = EMAIL ADDRESS REMOVED = >
> Subject: [WebAIM] resources on writing accessible user guides
>
> CAUTION: This email originated from outside of the organization. Do not
> click links or open attachments unless you recognize the sender and know
> the content is safe.
>
>
> Hi all,
> I'm looking for additional resources/guidelines about writing better user
> guides for websites/web applications, specifically:
>
> - Best practices for navigation description: instead of "click to the
> left of X..." I would tend towards using "select X under the Y
> heading."
> What are some other options?
> - Should we stop using sight-based idioms like "look" and "see"? Are
> those to be avoided in favor of "...find the X link after the Y
> heading" or
> "if you are searching for X, select the Y link under the Z heading...."
> Or is that over-thinking it?
> - What are recommendations on what interaction descriptor to use instead
> of "click?" Are "select" or "choose" good options? Any others?
>
> I really appreciate any help you can provide.
> Scott B.
> > > at http://webaim.org/discussion/archives
> > > > > >

From: Steve Green
Date: Fri, Apr 16 2021 10:22PM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

My experience is the same as Patrick's. I am in an email forum where blind and visually impaired people provide technical help for each other, and they use the same words as anyone else, like "click" and "see".

When writing test reports and procedures, our policy is to use the word "operate" for links and buttons, "select" for radio buttons and comboboxes, and "check" for checkboxes. In the context of these types of documents, it's important to only use hardware specific terms like "click" and "tap" when you really mean to only use those input methods. "Operate" is more appropriate if any input method can be used. However, I think it's ok to be less pedantic in other types of document, especially those intended for non-technical users.

Steve Green
Managing Director
Test Partners Ltd


-----Original Message-----
From: WebAIM-Forum < = EMAIL ADDRESS REMOVED = > On Behalf Of Scott Brackett
Sent: 16 April 2021 22:19
To: WebAIM Discussion List < = EMAIL ADDRESS REMOVED = >
Subject: Re: [WebAIM] resources on writing accessible user guides

Excellent! Thanks Patrick and Jonathan! I'd love to hear more if others have additional opinions/experiences to offer. These concrete examples are very helpful.


On Fri, Apr 16, 2021 at 3:59 PM Jonathan Avila < = EMAIL ADDRESS REMOVED = >
wrote:

> > Best practices for navigation description: instead of "click to
> > the
> left of X..." I would tend towards using "select X under the Y heading."
> What are some other options?
>
> Choose the items below or above is better than left or right -- refer
> to the understanding document for SC 1.3.3 (
> https://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-understanding.html).
> I've still had folks raise issue with after and before - but they are
> sequential for most mediums.
>
> > - Should we stop using sight-based idioms like "look" and "see"?
> > Are
> those to be avoided in favor of "...find the X link after the Y heading"
> or "if you are searching for X, select the Y link under the Z
> heading...." Or is that over-thinking it?
>
> I typically use other words like locate or refer to, etc.
>
> > - What are recommendations on what interaction descriptor to use
> instead of "click?" Are "select" or "choose" good options? Any others?
>
> "Choose" is another option
>
> Jonathan
>
> -----Original Message-----
> From: WebAIM-Forum < = EMAIL ADDRESS REMOVED = > On Behalf Of
> Scott Brackett
> Sent: Friday, April 16, 2021 2:28 PM
> To: WebAIM Discussion List < = EMAIL ADDRESS REMOVED = >
> Subject: [WebAIM] resources on writing accessible user guides
>
> CAUTION: This email originated from outside of the organization. Do
> not click links or open attachments unless you recognize the sender
> and know the content is safe.
>
>
> Hi all,
> I'm looking for additional resources/guidelines about writing better
> user guides for websites/web applications, specifically:
>
> - Best practices for navigation description: instead of "click to the
> left of X..." I would tend towards using "select X under the Y
> heading."
> What are some other options?
> - Should we stop using sight-based idioms like "look" and "see"? Are
> those to be avoided in favor of "...find the X link after the Y
> heading" or
> "if you are searching for X, select the Y link under the Z heading...."
> Or is that over-thinking it?
> - What are recommendations on what interaction descriptor to use instead
> of "click?" Are "select" or "choose" good options? Any others?
>
> I really appreciate any help you can provide.
> Scott B.
> > > archives at http://webaim.org/discussion/archives
> > > > archives at http://webaim.org/discussion/archives
> >

From: Mallory
Date: Sun, Apr 18 2021 1:31AM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

In tickets to developers (I know, they think and speak different than regular users), I use the word "actived" and "activated" a lot.

However if I didn't use words like "click", none of my non-technical family members would really follow instructions very well. My family thinks they're "clicking" on buttons when they smoosh their fingers against their phone screens.

As far as "look" and "see", I haven't met a blind person yet who doesn't "watch" movies or "sees" a TV show. I'm sure they're out there, and my personal bubble is definitely more the nerds than people like my family, but I'm just piling on to agree with Pat.

cheers,
_mallory

From: Karen McCall
Date: Sun, Apr 18 2021 3:54AM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

I'd also consider plain language and Easy Read guidance. One of the compliments I often get is that those who read by books and tutorials can understand what I'm talking about and guiding them through, especially technical processes.

I also use activate this or activate that as a more generic way of wording.

In terms of what I avoid. I avoid using ableist language like "enabled" and "disabled" when describing things. That is the only terminology that "grates on my nerves". 😊

I use available or not available. I can then describe why something is available or not available at a particular point in time.

Cheers, Karen

-----Original Message-----
From: WebAIM-Forum < = EMAIL ADDRESS REMOVED = > On Behalf Of Mallory
Sent: Sunday, April 18, 2021 3:32 AM
To: Steve Green < = EMAIL ADDRESS REMOVED = >; WebAIM Discussion List < = EMAIL ADDRESS REMOVED = >
Subject: Re: [WebAIM] resources on writing accessible user guides

In tickets to developers (I know, they think and speak different than regular users), I use the word "actived" and "activated" a lot.

However if I didn't use words like "click", none of my non-technical family members would really follow instructions very well. My family thinks they're "clicking" on buttons when they smoosh their fingers against their phone screens.

As far as "look" and "see", I haven't met a blind person yet who doesn't "watch" movies or "sees" a TV show. I'm sure they're out there, and my personal bubble is definitely more the nerds than people like my family, but I'm just piling on to agree with Pat.

cheers,
_mallory

From: glen walker
Date: Sun, Apr 18 2021 10:49AM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

Unless you're talking to developers, in which case the html attribute is
called "disabled".

On Sun, Apr 18, 2021 at 3:54 AM Karen McCall < = EMAIL ADDRESS REMOVED = > wrote:

> In terms of what I avoid. I avoid using ableist language like "enabled"
> and "disabled" when describing things. That is the only terminology that
> "grates on my nerves". 😊
>
>

From: Scott Brackett
Date: Mon, Apr 19 2021 10:37AM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

Thank you all for your responses! This is very helpful in helping me
determine a strategy for writing descriptive language in user vs. developer
documentation.


On Sun, Apr 18, 2021 at 11:49 AM glen walker < = EMAIL ADDRESS REMOVED = > wrote:

> Unless you're talking to developers, in which case the html attribute is
> called "disabled".
>
> On Sun, Apr 18, 2021 at 3:54 AM Karen McCall < = EMAIL ADDRESS REMOVED = > wrote:
>
> > In terms of what I avoid. I avoid using ableist language like "enabled"
> > and "disabled" when describing things. That is the only terminology that
> > "grates on my nerves". 😊
> >
> >
> > > > >

From: Pat Reynolds
Date: Wed, Apr 21 2021 2:34AM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

Is "actived" a typo? If it's a word, what does it mean?

Thanks,

Pat

On Sun, 18 Apr 2021 at 08:32, Mallory < = EMAIL ADDRESS REMOVED = > wrote:

> In tickets to developers (I know, they think and speak different than
> regular users), I use the word "actived" and "activated" a lot.
>
> However if I didn't use words like "click", none of my non-technical
> family members would really follow instructions very well. My family thinks
> they're "clicking" on buttons when they smoosh their fingers against their
> phone screens.
>
> As far as "look" and "see", I haven't met a blind person yet who doesn't
> "watch" movies or "sees" a TV show. I'm sure they're out there, and my
> personal bubble is definitely more the nerds than people like my family,
> but I'm just piling on to agree with Pat.
>
> cheers,
> _mallory
> > > > >


--
*- -*

*Dr Pat Reynolds*
Executive Director


A Charitable Incorporated Organisation registered in England and Wales,
number 1167484
VAT registration: 233 0105 70

*Join us on social:*
[image: : https://www.facebook.com/FreeUKGEN]
https://www.facebook.com/FreeUKGEN <https://twitter.com/FreeUKGen>
<https://www.instagram.com/freeukgenealogy/>
<https://www.pinterest.co.uk/FreeUKGenealogy/>
Please read our *Privacy Notice*
<https://www.freeukgenealogy.org.uk/files/Documents/Privacy-Notice.pdf> for
information on how we will protect and use your data.

<https://www.easyfundraising.org.uk/causes/freeukgenealogy/?utm_campaign=raise-more>

​+44 ​1723 362616 ​ +44 7943 145387
Westwood House,Westwood, Scarborough YO11 2JD, UK

From: glen walker
Date: Wed, Apr 21 2021 1:05PM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

Most likely a typo. In context, they probably meant "active" and
'activated". I suspect muscle memory kicked in and when typing "active",
the finger naturally typed a 'd' at the end.

Happens to me all the time with certain words. Like intending to type
"director" but my fingers always add a "y" at the end because I type
"directory" more often than I type "director".

On Wed, Apr 21, 2021 at 2:35 AM Pat Reynolds <
= EMAIL ADDRESS REMOVED = > wrote:

> Is "actived" a typo? If it's a word, what does it mean?
>
> On Sun, 18 Apr 2021 at 08:32, Mallory < = EMAIL ADDRESS REMOVED = > wrote:
>
> > In tickets to developers (I know, they think and speak different than
> > regular users), I use the word "actived" and "activated" a lot.
>

From: Pat Reynolds
Date: Thu, Apr 22 2021 2:20AM
Subject: Re: resources on writing accessible user guides
← Previous message | Next message →

Many thanks! I do that, too.

Best wishes,

Pat

On Wed, 21 Apr 2021 at 20:05, glen walker < = EMAIL ADDRESS REMOVED = > wrote:

> Most likely a typo. In context, they probably meant "active" and
> 'activated". I suspect muscle memory kicked in and when typing "active",
> the finger naturally typed a 'd' at the end.
>
> Happens to me all the time with certain words. Like intending to type
> "director" but my fingers always add a "y" at the end because I type
> "directory" more often than I type "director".
>
> On Wed, Apr 21, 2021 at 2:35 AM Pat Reynolds <
> = EMAIL ADDRESS REMOVED = > wrote:
>
> > Is "actived" a typo? If it's a word, what does it mean?
> >
> > On Sun, 18 Apr 2021 at 08:32, Mallory < = EMAIL ADDRESS REMOVED = > wrote:
> >
> > > In tickets to developers (I know, they think and speak different than
> > > regular users), I use the word "actived" and "activated" a lot.
> >
> > > > >


--
*- -*

*Dr Pat Reynolds*
Executive Director


A Charitable Incorporated Organisation registered in England and Wales,
number 1167484
VAT registration: 233 0105 70

*Join us on social:*
[image: : https://www.facebook.com/FreeUKGEN]
https://www.facebook.com/FreeUKGEN <https://twitter.com/FreeUKGen>
<https://www.instagram.com/freeukgenealogy/>
<https://www.pinterest.co.uk/FreeUKGenealogy/>
Please read our *Privacy Notice*
<https://www.freeukgenealogy.org.uk/files/Documents/Privacy-Notice.pdf> for
information on how we will protect and use your data.

<https://www.easyfundraising.org.uk/causes/freeukgenealogy/?utm_campaign=raise-more>

​+44 ​1723 362616 ​ +44 7943 145387
Westwood House,Westwood, Scarborough YO11 2JD, UK

From: Mallory
Date: Thu, Apr 22 2021 11:58AM
Subject: Re: resources on writing accessible user guides
← Previous message | No next message

yup, typo that I didn't even see when I quickly re-read it before Sending.

On Thu, Apr 22, 2021, at 10:20 AM, Pat Reynolds wrote:
> Many thanks! I do that, too.
>
> Best wishes,
>
> Pat
>
> On Wed, 21 Apr 2021 at 20:05, glen walker < = EMAIL ADDRESS REMOVED = > wrote:
>
> > Most likely a typo. In context, they probably meant "active" and
> > 'activated". I suspect muscle memory kicked in and when typing "active",
> > the finger naturally typed a 'd' at the end.
> >
> > Happens to me all the time with certain words. Like intending to type
> > "director" but my fingers always add a "y" at the end because I type
> > "directory" more often than I type "director".
> >
> > On Wed, Apr 21, 2021 at 2:35 AM Pat Reynolds <
> > = EMAIL ADDRESS REMOVED = > wrote:
> >
> > > Is "actived" a typo? If it's a word, what does it mean?
> > >
> > > On Sun, 18 Apr 2021 at 08:32, Mallory < = EMAIL ADDRESS REMOVED = > wrote:
> > >
> > > > In tickets to developers (I know, they think and speak different than
> > > > regular users), I use the word "actived" and "activated" a lot.
> > >
> > > > > > > > > >
>
>
> --
> *- -*
>
> *Dr Pat Reynolds*
> Executive Director
>
>
> A Charitable Incorporated Organisation registered in England and Wales,
> number 1167484
> VAT registration: 233 0105 70
>
> *Join us on social:*
> [image: : https://www.facebook.com/FreeUKGEN]
> https://www.facebook.com/FreeUKGEN <https://twitter.com/FreeUKGen>
> <https://www.instagram.com/freeukgenealogy/>
> <https://www.pinterest.co.uk/FreeUKGenealogy/>
> Please read our *Privacy Notice*
> <https://www.freeukgenealogy.org.uk/files/Documents/Privacy-Notice.pdf> for
> information on how we will protect and use your data.
>
> <https://www.easyfundraising.org.uk/causes/freeukgenealogy/?utm_campaign=raise-more>
>
> ​+44 ​1723 362616 ​ +44 7943 145387
> Westwood House,Westwood, Scarborough YO11 2JD, UK
> > > > >