Accessibility for Writers: Software Manuals

One of the most important improvements that can be made to the accessibility of a site is a task that will often fall to writers.  Adding text to describe images allows blind and visually-impaired users to access your content, but writing it is not necessarily something that comes naturally.  The tips compiled here will help you get started and avoid common pitfalls.

If the software you are writing about is not yet accessible, it may help to consider the perspective of a blind parent trying to help their sighted child.  Or a blind and a sited spouse learning to use tax software together.  The example often cited is the nephew who is considering joining the millitary and his visually-impaired aunt who goes on the web to look up information about college funds for soldiers.  Even if the application itself isn’t or can’t be made accessible the manual can and should be.  However, to the extent that the software can be operated by disabled visitors the long descriptions should describe how a blind visitor would use the software.

There are three options available for adding text to images:

  1. Alternative text – the easiest accessibility feature to add and the most important in terms of added accessibility.  Essential information is included in the alternative description. It is specified using the element alt="[enter essential information here]"
  2. Title – used for adding something extra to your descriptions.  You can be more creative with the title.  It is specified using the attribute title="[Enter longer, more creative, extra information here]"
  3. Long description – with complicated images like screen shots or images that convey a lot of meaning to the viewer long description is used.  It is specified using the longdesc="[Enter url of long description here]"

Alternative Text –

Pink Water lillies and blue padsYou’ve probably already noticed Contribute prompting you for alt text when you insert images, but maybe you weren’t 100% certain what the appropriate text should be.

Alt text should be used to describe what something is, represents, or does.  For instance, this picture of water lilies could have the alt text "Water lilies on Ames Pond".  Alternate text should be a summary of what the photo is in few words. 

Section 508 regulations require that this text be an equivalent to what a sighted person sees when looking at the image, but also stipulates that it not be long or vague.  The struggle is to be balance accuracy with brevity. 

Alt text should never be longer than 1024 characters.  Generally, it should be just a few words.  It is important to keep in mind that everything on a page has to be read aloud to someone who can’t see the screen.

You might have asked yourself "What something does", how can an image "do" something?  Occasionally images are used for links.  In this case the alt text should tell the user what will happen if they follow the link.  For instance if the link leads to a page about ponds in Maine, it should say "Maine Ponds" or something similar. 

Common pitfalls:  Never use the phrase "Picture of" or "Link to" in your alt text.  The screen reader will already have informed the user that the text refers to a link or a photo.  It is easy to imagine how this would get irritating to hear twice every time the user encounters an image.

Alt text must be included for absolutely every image every time.  However, there are times when an image doesn’t really serve a function.  For instance images used solely for layout purposes like borders, rules, textures, rounded corners, and sometimes logos.  In this case you should include alt="".  This tells the screen reader to skip over the image entirely.  If you don’t include this convention the user will hear over and over IMAGE IMAGE IMAGE, and wonder what they are missing. 

Tour ButtonAlt text should always be considered in the context of the document in which it is included.  For Instance, software manuals often contain buttons and descriptions of those buttons.  In the actual program the alt text might be "Take a tour" or "Tour the Reader", but in the context of a guide about the software the alt text should be "Tour Button" or something similar since the important thing is that the user be able to identify the button and apply that information to using the software.

For screen shots where we will also include a long description the alt text should be "Library Screen shot – long description".  This will let the user know that the image is both the library screen shot and a link to it’s long description. 

Long Description –

Long descriptions are separate web pages used to describe complex images such as screen shots which cannot be completely summarized by their alt text or their context.

Title Page Screenshot - long descriptionJoe Clark suggests long descriptions be kept in the same directory and use the same filename as the image they describe,  adding -LD at the end of the file name for easy identification.  For instance, the following image "TitlePage.png" would have a long description called "TitlePage-LD.html". 

Long descriptions are simple text only pages which use words to describe what the user cannot see.  The title should be "Long description for TitlePage.png". 

Screen Shots:

Use these guidelines when writing descriptions of screen shots. 

You can see an example of a long description by clicking on the image above.

  • Describe what you see.
  • Imagine that you were a blind teacher trying to explain to a student how to navigate that particular screen.  What would they need to know?  Tell the student how to find the different functions using only words.
  • Work from the top left to the bottom right and describe things in order.  (as the english language is read from left to right, and we are writing in English)
  • When sections of the screen shot look like tables or lists, describe them as such. 
  • Using grouping words like column, navigation bar, band, etc to group related portions of the Screen shot will make your descriptions easier to read.
  • Language should match the image.  Administrative screen shots should be described with functional language, whereas fun screen shots from the application should be described with more detail. 
  • Refer to color, shapes, or other presentational devices that would help a blind teacher or parent to tell the student what to look for.
  • Avoid describing the same things multiple times.  If we have already created a long description for the library and then you write a long description for a specific screen within the library it is enough to include a phrase like "In a yellow bar across the top are the typical controls found in the library." and make the word library a link to the more general description of the library.
  • The long description is included to make the image useful in it’s context.  You may, if it is absolutely necessary to make the description more comprehensible, include information that is also in the text of the document, but generally it should be unnecessary. 
General Images:

Read Joe Clarks advice on how to write a long description for a photo.  While this article deals with writing long descriptions for screen shots, his approach can help you start to understand what information to include.



One thought on “Accessibility for Writers: Software Manuals”

  1. Pingback: Stubbornella

Comments are closed.