LANGUAGE GUIDELINES FOR FAQ WRITERS AND SITE TRANSLATION TEAM

[ivorygates]

Rho asked me to work with the Accessibility Team to prepare with a guidelines document for the FAQs writers and the Translation Team that would help us frame all site language in ways that would render the site optimally-accessible for all users, no matter how they are accessing the site. This is the first-pass document, primarily culled from the thread in dw_docs that originally framed that discussion, and from the work of zvi, rb, jadelennox and others who posted there and who I probably forgot to name.

In the material that follows, the term "site documents" or "site docs" will be used interchangeably to refer to FAQs, translation strings, and any other site-generated material on the Dreamwidth site.

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. The ideal is to create language that seems both naturalistic and inclusive. You will find yourself making the site documents much longer than their originals. Don't worry about this. You will also find yourself thinking that their language is redundant. It is better to be redundant than to be confusing.

As much as possible, site docs shouldn't be written with the assumption that the eventual reader will be seeing the same images and screen ratios as the writer is, nor that they'll be interacting with their computer with the same input devices as the writer has. On the one hand, you have people who are differently-abled 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 people out there still cruising in lynx, not to mention that Dreamwidth will support different siteschemes, and people will do all manner of funky things with their journal styles.

Whenever possible, instead of describing a visual element (which may or may not be meaningful to someone cruising the site with a screenreader or Braille device), include a link to the element in question. 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.

When that isn't possible, include the image and its alt-text as it will appear on the site, with a note that it's the site default.

Be aware at all times of visio-spatial issues with site language, and avoid any language which requires the user to be seeing the same site visually or using the mouse or keyboard like the site docs writer. For example, if 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], the language needs to be revised to make it more inclusive.

Avoid the use of the word "see", replacing it wherever possible with "display" or "read", both of which are functions that are cross-accessibly site-available. "Displayed" is more inclusive than "visible" or "seen", and it acknowledges that people may be reading via text-to-speech or Braille display.

Avoid using the phrase "click here", as it does not provide enough information to people using a screen reader. Hyperlinks should contain enough information to allow people using screen readers to know where the hyperlink leads. (A screen-reader will read out the text of a hyperlink to its user: you can access a demonstration of one on YouTube here: http://www.youtube.com/watch?v=-GPNTctdezg&feature=related)

Suggested language:

"follow" links rather than "click on" links
"enter" text rather than "type" text
replace "you will see X" with "X will be"

There doesn't seem to be a better verb than "click on" for buttons. Select? Choose?

It's important to avoid mouse-specific language such as "click" or keyboard-specific language such as "type". Don't assume people can see icons: if recognition of an icon is required for documentation, describe it and also refer to it by its alt-text. Don't assume people can see colors, or that their page layouts are going to be controlled successfully by CSS.

The Firefox Accessibility Extension ( http://firefox.cita.uiuc.edu/ ) makes it easier for people with disabilities to view and navigate web content. Developers can use the extension to check their use of structural and styling markup that support functional web accessibility.

[Okay, this is as much as I've got so far. Have at it...]

Comments

[denise]

This is great!

one small suggestion though:

replace "you will see X" with "X will be displayed"

I'd prefer active voice whenever possible, so instead of "X will be displayed", how about "X will show", or even better, just a plan "X will be"?

[ivorygates]

Oh *slaps forehead* of course you're right! In addition to everything I've written here, the site docs must conform to the Dreamwidth Style Guidelines: http://wiki.dwscoalition.org/notes/Manual_of_Style

(goes to tweak)

[mark]

Thank you for doing this. It's very informative and useful for me to read, even if I'm not doing copy. :)

[ivorygates]

Yay!

[rho]

Thank you for doing this! I know we're going to get this wrong a whole lot, but it makes me so damn proud and happy that it's something that we're at least trying to get right from the start.

One thing I'm note entirely clear about is the title attribute? Can you give me an example of precisely how that's meant to work?

[ivorygates]

I need to kick that one back to zvi because that's cribbed ENTIRELY from her: 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.

Wikipedia has totally failed in explaining to me what a "title attribute" is, so... help?

[zvi]

Oh! Yes, okay. When you write <a href=site.tld/path title="What the Page is really Called">some other text which does not match the page title but you feel like linking with anyway</a>, the title attribute is the part that's "What the Page is really Called."

I don't know precisely what screenreaders or other accessible devices do with that information, but I know it's helpful.

Also, to back up a bit, in HTML, the tag is when you're marking up a document and saying "This bit of info I've surrounded with a tag is this sort of thing," so like <b> is the bold tag and <p> is the paragraph tag. <a> is the anchor tag. If the tag has to be modified in some way, you indicate that with an attribute. The most common attribute with the anchor tag is the href, which tells you "this text being surrounded by the anchor tag should be a link to stuff here." What the title attribute tells you is "The thing that I am linking to is actually called this." So, say, in Firefox, the title is often shown as a tooltip. And if you have a tool that's parsing the HTML document for links, instead of grabbing the link and calling it "You gotta see this!" (the stuff surrounded by the anchor) it can call it "Rickrolled, suckas!" if someone has given the link the title of "Rickrolled, suckas!"

[lightgetsin]

I think this is useful in cases where my screenreader needs to search for alternative link descriptions for me, which generally happens on graphical links and image maps where the information otherwise available is just a file name or a string of numbers. It's one of those invisible things it does that I'm not actually sure about.

[rainbow]

This is very helpful! Thank you for putting it together.

[ivorygates]

i'm glad it's helpful! and anything you can think of to add, please jump in!

[rainbow]

Okay, what about things like this:

Code: /directory.bml.browse.usa.desc

Select a US state on the map, or a country from the list beneath it, to read journals from that place.

If a map's used, is there a way to make it usable for the visually challenged? Or should it be changed to a list? The point and click maps are common, but so is making things default to sightedness....

[lightgetsin]

I think it depends on the map -- most are completely inaccessible, but I've seen a few that have alt tagged every state. The remaining issue in that case is that in a non-graphical format, the states are in a completely bizarre order and it's a pain to find yours without just doing a "find" on the page. My suggestion is just to have an available alternative in a list box.

[rho]

I've opened up an issue in our bug tracker for adding in a text list as well. Can't say when we're likely to get it done, but at least it's on our radar now. Thanks for the input.

[lightgetsin]

Well done! Two thoughts, from the perspective of a screenreader user who interacts entirely with the web in audio formats.

using the mouse or keyboard like the site docs writer. For example, if 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], the language needs to be revised to make it more inclusive.


Yes, though my preference would actually be to keep the visual language and add a nonvisual descriptor (e.g. follow the link marked x, which I will often opt to just text search for on a page, btw). I think it's actually most useful to think about this as a universal design problem, and the flat truth is you're not going to find a single perfect reference point for everybody. There are enough purely visual navigators out there who would frankly be thrown by the instructions that I find most useful. Longer docs, like you said, but worth it.

Also, a weird language point. When you coin new words or compress existing words, they are often mispronounced by screenreaders. For example, I had to pause a beat to parse what sitescheme was (it was read to me as "sitascheem," which is a pretty good sounding it out guess on the part of my software. I'm a very experienced user, so things like that don't trip me up much. But a new user would find it very confusing. Easy solutions are to either not compress words like that and keep a space, or to capitalize like SiteScheme, which gives my software enough info to get it right.

Lastly, perhaps we "push" a button? I dunno.

[kyrielle]

Perhaps you could push a button, as suggested, or "use" a button?

Also, I'm not sure if this is where to mention this, but when I'm on a DW site scheme page, the drop-down for the search offers "site & account" but when I'm in a journal page, the navigator drop-down for the search offers "site & user" - clear, but inconsistent.

[kyrielle]

Unrelated: on http://www.dreamwidth.org/register.bml after an open id account validates email and the Dreamwidth 101 displays (hopefully faster once out of beta), the first item seems inappropriately phrased for an OpenId account:

What is a journal?
Your journal is for writing and sharing stories, photos, videos, and more with others.

...since there isn't a journal for an OpenId account. It links to a page that says as much, but that might frustrate a complete novice who hasn't used an OpenId login on an LJ clone before.