zvi: self-portrait: short, fat, black dyke in bunny slippers (Default)
still kind of a stealthy love ninja ([personal profile] zvi) wrote in [site community profile] dw_docs2009-04-02 11:46 am

Accessibility issue

I pointed out a sort of overarching issue with the FAQ documentation as currently written to rho, and, in traditional DW fashion, she asked me to take the first pass at solving it.

The problem is that some of the documentation is written with visual, spatial, or movement-specific language. To the extent possible, FAQs/sitedoc should not be written with the assumption that the eventual reader is going to be seeing the same images and screen ratios, nor that they'll be interacting with their computer with the same input devices as the writer's. On the one hand, you have people with disabilities using the site; on the other hand, you have people with an array of mobile devices using the site; and on the third hand, you have a few people out there still cruising in lynx, because they're Richard Stallman. (Not to mention that we'll support different siteschemes, and people will do all manner of funky things with their journal styles.)

I'm going to do a first sweep through the FAQ docs as currently written, but I strongly suggest you guys hook up with the Accessibility team for more expert advice. (For instance, I am unsure about whether or not dropdown menu is a term that is meaningful on a screenreader.) My inexpert advice is that, wherever possible, instead of describing a visual element, you include the image and its alt-text as it will appear on the site (maybe with a note that it's the site default?), and if you can skip the visual element and just link to the thingy in question, that's even better.

By visuospatiai issue, I mean that the FAQ says "perform this motion" for interacting with the site, or "item found to the left of second item" or "choose the [textual description of image] to accomplish task" Any language which requires the user to be seeing the same site visually or using the mouse or keyboard like the writer.

Additionally, all link text should be meaningful ("Choose your sitescheme" instead of "click here to"), and, a title attribute should be set when the link text doesn't match the page title of the page the link refers to.

FYI Each tab of my account settings has a URL, so you can link directly to that tab.

FAQ's w/ visuospatial language

How do I confirm my email address? typed rather than entered

How do I change my email address? verbal redirect to settings tab

How do I change my password? verbal redirect to settings tab

How do I post an entry? vs

How do I post an entry to a community (or alternative journal)? vs

How do I restrict who can see my entry? vs

How can I choose which usericon to use? vs

How do I edit or delete an entry? vs

How does comment threading work? vs

What happens when there are large numbers of comments? uses "see" a lot

What are the limits on comments? see

Can I edit or delete my comment? vs

What can I do with comments posted to my journal? vs

How do I control who can comment on my journal? settings tab; vs

What is comment screening? vs

What is comment IP logging? settings tab, vs

What is a profile and how do I update mine? vs

How do I subscribe to other journals? vs

How do I grant access to my protected content to other journals? vs

How do I unsubscribe or revoke access from another journal? vs

What are notifications? settings tab

What is tracking? This might be a good model for how to deal w/ images that will be changed on user site schemes!

How do I stop tracking something? settings tab

P.S. Psst. [personal profile] forthwritten. May want to include site-specific URL forms in What Dreamwidth specific markup can I use?. All the lj were replaced with site.

[personal profile] rho 2009-04-03 07:25 am (UTC)(link)
Thanks for taking the time to do this! I definitely want to try to make sure our docs are awesome from an accessibility standpoint, so this sort of correction is very welcome. Speaking only for myself, I know I have a lot to learn on this front. I'll poke at [personal profile] rb next time I get a chance to see if we can come up with some way of coordinating this properly.
jeshyr: Blessed are the broken. Harry Potter. (Default)

[personal profile] jeshyr 2009-04-07 12:09 pm (UTC)(link)
My suggestion would be to have a "best practices of inclusive language" guide which supplements the style manual.

The trickiest bit is balancing the use of language that normative (this means 'statistically average' BTW) users expect such as "click here", and language which is more inclusive and helpful. If you go too far in the other direction it becomes difficult for people to understand.

Suggestions:
- "follow" links rather than "click on" links
- "click on" buttons though, because there's just no better verb
- "enter" text rather than "type" text

You've all been so quick at updating the links [personal profile] zvi provided that I can't spot a lot of the problems any more! Might need more examples?
jadelennox: Senora Sabasa Garcia, by Goya (Default)

[personal profile] jadelennox 2009-04-07 02:44 pm (UTC)(link)
As many times as I see dw's commitment to accessibility, something new always comes up which floors me. [personal profile] zvi, seeing somebody outside the accessibility evangelist or disability community expressing concern about exclusive language in documentation is just not something I have ever seen in my life. *wipes away a little tear*

All that being said, I completely agree with [personal profile] rb here that having a best practices guide supplementing the style manual for all site copy is a good idea. Most of the things which immediately come to mind have already been mentioned here in this post and comments: meaningful link text (this is the most important one for usability), no mouse-specific language such as "click" or keyboard-specific language such as "type". No assuming that people can see icons: if an icon is required for documentation and describe it but also refer to it by its alt text. No assuming that people can see colors, or that page layout is going to be controlled successfully by CSS.

I think it would be very interesting to turn off CSS and images and see if the documentation still works. It would also be interesting to turn off CSS, images, and unplug a mouse and see if the documentation still works, although this requires having a tester who knows how to navigate the Web without a mouse. Luckily, our code makes it pretty easy. :-)
jeshyr: Pile of thick books labelled "Geek" (Geek)

[personal profile] jeshyr 2009-04-07 03:10 pm (UTC)(link)
I agree it's totally mind-blowing to have a project that cares about accessibility so much and in so many directions! \o/

I mostly agree about 'click' and 'type' but can you think of appropriate language for submitting forms where the buttons aren't labeled 'submit' and users don't usually know what "sumbit the form" means? I can't think of clearer language than 'click on the BLAH button', personally.

And about your CSS/images test - I usually load images (although I have 'use placeholders' set for everything but small ones) but my basic method of reading involves wiping all site-loaded CSS and most other formatting and replacing it with what suits my eyes - white text on green. I read everything that's longer than 2-3 paragraphs this way, so pretty much all journal stuff.

I have a bookmarklet that does it, for anybody that's interested you can try this one:

Zap Formatting And Replace With Ricky's

(For those unfamiliar with bookmarklets, it'll go back to normal if you reload the page or click on any link). I think I got the escaping on that right, I guess I'll see when I post it ...

The bookmarklet's built for Firefox but last I checked it worked in Safari too so it should work with Chrome. No guesses about MSIE though. If it actually looks useful to you guys I can easily modify it so it leaves you with black text on white - probably easier for those with normal eyesight!

(Actually I have 3 bookmarklets, this is the "first level" one and there's two more than do heavier duty formatting removal for stubborn sites with nasty things like tables for layout. Happy to share if anybody's interested.)

Cheers,
r
Edited 2009-04-07 15:20 (UTC)
jeshyr: Blessed are the broken. Harry Potter. (Default)

[personal profile] jeshyr 2009-04-07 03:21 pm (UTC)(link)
OK, I totally fail with the bookmarklet thing. If somebody can urlencode the @$*&( thing properly and post it that'd be cool. I might fight with it tomorrow if I have the energy - bed time now.
jadelennox: Senora Sabasa Garcia, by Goya (Default)

[personal profile] jadelennox 2009-04-07 03:33 pm (UTC)(link)
Another good way to test,in Firefox is using this fantastic accessibility extension. I use it to turn off accesskeys (which interfere with all of my shortcuts), but it has some great testing features. Opera has a whole slew of built in stylesheets, including some designed for accessibility, which can also show you how a webpage might look for people using accessibility software. (On opera, they are in the "view" menu.)
lferion: Art of pink gillyflower on green background (Default)

[personal profile] lferion 2009-04-03 06:32 pm (UTC)(link)
Would it be useful to put specific examples in the style guide (or a wiki page attached to the Manual of Style)? I know that I am Very Ignorant in this area, so a few 'inaccessible' -> 'somewhat accessible' -> 'widely accessible' examples ranging from blatant to subtle would be/could be very helpful, both in understanding the underlying issues and creating better documentation.
forthwritten: stained glass spiral (Default)

[personal profile] forthwritten 2009-04-04 09:58 am (UTC)(link)
Thanks for this - mine are in a very raw state, so it's useful to have this as a reminder. I hesitated over putting site-specific URL forms in the same FAQ - I intended the DW specific markup FAQ to be referenced for new users and site-specific URLs might confuse them.
jeshyr: Blessed are the broken. Harry Potter. (Default)

[personal profile] jeshyr 2009-04-07 12:13 pm (UTC)(link)
For What happens when there are large numbers of comments? you could replace "see" with "display" as in "only the first comment in each thread is displayed".

I think "displayed" is more medium-agnostic than "visible" or "seen", recalling that people may be reading via text-to-speech or braille display.
cesy: "Cesy" - An old-fashioned quill and ink (Default)

[personal profile] cesy 2009-04-07 03:44 pm (UTC)(link)
I love that you're making the effort on stuff like this.
liv: cartoon of me with long plait, teapot and purple outfit (mini-me)

[personal profile] liv 2009-04-12 04:16 pm (UTC)(link)
Thank you so much for this. I've gone through the comment ones and tried to fix them up to meet these standards. I think if there's a button I have to describe it visually as well, since sighted users are not going to look for the alt text on buttons. But I have got rid of the settings page tabs, and replaced "you will see X" with "X will be displayed", and so on.
ivorygates: (Default)

accessibility guidelines for doc and copy writers

[personal profile] ivorygates 2009-04-13 02:32 am (UTC)(link)
Hi! I'm on the site copy team, and I mentioned to [personal profile] rho that some of the translation strings (translation: all the words you see on your screen that are displayed by the site are called for some arcane reason "translation strings") I'm seeing are using language that privileges sighted or an otherwise narrowly-abled class of user, and she asked me to work with the Accessibility People to come up with a guidelines document for the FAQs writers and the Translation Team (we don't actually translate anything, which confused me at first; it just means we're working with the translation strings) that would avoid having the site say things that just *aren't right* for a certain segment of its userbase.

And the last thing I want is to step on anybody's toes, or come swanning in when somebody else has already been *doing* that. (Just slap me. Hard.) I'm going to go back through everything you've said here, [personal profile] zvi, and the rest of this thread, and pull together a preliminary single document, and also try to chase down rickyb.

One of the problems I'm having when I work on the translation strings, I'll say right up front, is having no idea of what they do "in the wild" (what the page would look like, what actual function the string performs, or where it does it). So I'm thinking that fixing this may be a case of first making all the language (on the translation strings; I don't know where we are in the FAQs) conform to DW standard (and we're almost done with that!) and then combing the whole site to see them "in use" and revising them a second time. (What do you think?)

Of course, the Accessibility Guidelines Work Document will also apply to/be a resource for the people re-writing the FAQs, so... useful all around.