Ivorygates (![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png)
ivorygates) wrote in ![[site community profile]](https://www.dreamwidth.org/img/comm_staff.png)
dw_docs2009-04-13 12:39 am
ivorygates) wrote in dw_docs2009-04-13 12:39 am
Entry tags:
LANGUAGE GUIDELINES FOR FAQ WRITERS AND SITE TRANSLATION TEAM
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...]
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...]
no subject
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?
no subject
Wikipedia has totally failed in explaining to me what a "title attribute" is, so... help?
no subject
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!"
no subject