<chapter id="accessibility"> 
  <title>Writing Accessible Documentation</title> 
  <para> This chapter provides some basic guidelines for writing GNOME
	 documentation for users with disabilities. </para> 
  <para> </para> 
  <sect1 id="accessibility-1"> 
	 <title>Assistive Technologies</title> 
	 <para> Wherever possible, consider the requirements of the following groups
		of users when you write documentation: 
		<itemizedlist> 
		  <listitem> 
			 <para> Users with cognitive impairments </para> 
		  </listitem> 
		  <listitem> 
			 <para> Blind users and users with other vision impairments </para> 
		  </listitem> 
		  <listitem> 
			 <para> Deaf users and users with other hearing impairment </para> 
		  </listitem> 
		  <listitem> 
			 <para> Paralyzed users and users with impaired motor skills </para> 
		  </listitem> 
		</itemizedlist> </para> 
	 <para> Assistive technologies exist to help computer users with various
		disabilities. An example of assistive technology is the screenreader, which
		blind people use to view a GUI and read online text. A screenreader normally
		translates text into synthesized speech or a refreshable Braille display.
		</para> 
  </sect1> 
  <sect1 id="accessibility-2"> 
	 <title>Information Design Considerations</title> 
	 <para> Consider the following factors relevant to disabled users when you
		write documentation: 
		<variablelist> 
		  <varlistentry> 
			 <term>Text blocks</term> 
			 <listitem> 
				<para> Long text blocks can be difficult to read for people who use
				  screenreaders. Also, readers whose first language is not standard English,
				  including some deaf people, can find long text blocks difficult to understand.
				  Keep your text blocks short. See <xref linkend="access-writing"/> for more
				  information. </para> 
			 </listitem> 
		  </varlistentry> 
		</variablelist> 
		<variablelist> 
		  <varlistentry> 
			 <term>Graphics</term> 
			 <listitem> 
				<para> Do not overuse graphics, especially when you write online
				  Help. A graphic that merely repeats a text message can frustrate someone who
				  is using assistive technology to read the Help. Provide descriptions that do
				  not require graphics. To test whether you need a graphic, remove the graphic,
				  then check whether you can still work out what to do. If you need to use a
				  graphic, make sure that you include a text equivalent of the graphic. See
				  <xref linkend="access-images"/> for more information. </para> 
			 </listitem> 
		  </varlistentry> 
		</variablelist> 
		<variablelist> 
		  <varlistentry> 
			 <term>Tables</term> 
			 <listitem> 
				<para> Tables can cause problems for screenreaders that read the
				  content of all the cells as a single, continuous line of text. Use tables for
				  genuinely tabular information only. Do not use tables merely as a layout
				  technique. Ensure that tabular information makes sense if you read the cells in
				  sequence from left to right, starting from the top left cell in the table.
				  </para> 
			 </listitem> 
		  </varlistentry> 
		</variablelist> </para> 
  </sect1> 
  <sect1 id="access-writing"> 
	 <title>Accessible Writing Techniques</title> 
	 <para> The following guidelines can help you to develop an accessible
		writing style: 
		<itemizedlist> 
		  <listitem> 
			 <para> Write concise descriptions to help people with cognitive,
				vision, and hearing impairments. As recommended elsewhere in this guide, keep
				sentences to one idea. Do not ramble. </para> 
		  </listitem> 
		  <listitem> 
			 <para> Keep the number of steps in procedures to a minimum. More than
				seven procedural steps can create problems for all users, but pose additional
				difficulties for people with cognitive impairments. </para> 
		  </listitem> 
		  <listitem> 
			 <para> Do not use directional instructions, if at all possible, such
				as above, below, left, right. Users who are using a screenreader might have
				difficulty finding the directions on screen. Some users with cognitive
				impairments might have difficultly understanding the spatial concepts. </para> 
		  </listitem> 
		  <listitem> 
			 <para> Emphasize important information near the beginning of the
				text, so that blind users and users with cognitive impairments can assess
				whether they need to read further. </para> 
		  </listitem> 
		</itemizedlist> </para> 
  </sect1> 
  <sect1 id="access-images"> 
	 <title>Text Equivalents for Graphics</title> 
	 <para> Graphics such as illustrations, icons, photos, screenshots, and
		thumbnails all require text equivalents for use with assistive technologies.
		Each text equivalent should briefly identify the graphic and, if appropriate,
		describe any functionality that the image represents. The text equivalent must
		be brief, descriptive, and accurate. You need to include as much information as
		possible into the fewest number of characters without sacrificing
		intelligibility </para> 
	 <sect2 id="accessibility-3"> 
		<title>Creating Text Equivalents</title> 
		<para> A text equivalent should describe the visual appearance of the
		  graphic. The text equivalent can also include instructions on how to take an
		  action, such as how to select options in a dialog. Ideally, a text equivalent
		  provides the user with the same information as the original graphic. To find
		  out how to implement text equivalents in your documentation, see the 
		  <ulink url="http://developer.gnome.org/projects/gdp/handbook.html"> 
			 <citetitle>GNOME Handbook for Writing Software
				Documentation</citetitle></ulink>. </para> 
	 </sect2> 
	 <sect2 id="accessibility-4"> 
		<title>Writing Good Text Equivalents</title> 
		<para> To comply with Part 1194.22 in Section 508 of the Rehabilitation
		  Act: Electronic and Information Technology Accessibility Standards,
		  documentation must include a text equivalent for each graphic in documentation.
		  </para> 
		<para> Follow these guidelines when you write text equivalents: </para> 
		<itemizedlist> 
		  <listitem> 
			 <para> At a minimum, include the graphic content and the label of the
				item in the graphic. For example, "Run Application dialog." </para> 
		  </listitem> 
		  <listitem> 
			 <para> If the contents of the graphic are not complex, describe the
				contents of the graphic. For example, "Run Application dialog. Contains command
				drop-down combination box, Browse button, Run in terminal check box. Contains
				Run, Cancel, Help buttons." </para> 
		  </listitem> 
		  <listitem> 
			 <para> If the contents of the graphic are complex, summarize the
				contents of the graphic. For example, "Miscellaneous tabbed section. Contains
				controls to set miscellaneous Sawfish options. Contains Done, Cancel buttons."
				</para> 
		  </listitem> 
		  <listitem> 
			 <para> If the order of use of elements in a graphic is not clear,
				describe the elements in top-to-bottom, left-to-right order. </para> 
		  </listitem> 
		  <listitem> 
			 <para> If the graphic is annotated, list the callouts in order of the
				elements that are illustrated. This is not necessarily the same as the order in
				which the callouts appear. For example, "Crux window titlebar. Callouts: Window
				Menu button, Titlebar, Minimize, Maximize, Close Window buttons." </para> 
		  </listitem> 
		</itemizedlist> 
	 </sect2> 
  </sect1> 
  <sect1 id="accessibility-5"> 
	 <title>More Information About Accessibility</title> 
	 <para> For more information about accessibility topics, read the following
		documents: 
		<itemizedlist> 
		  <listitem> 
			 <para> 
				<ulink
				 url="http://www.sun.com/access/developers/access.quick.ref.html"> 
				  <citetitle>Accessibility Quick Reference
					 Guide</citetitle></ulink>, Sun Microsystems </para> 
		  </listitem> 
		  <listitem> 
			 <para> 
				<ulink url="http://www.rnib.org.uk/digital/hints.htm"> 
				  <citetitle>RNIB Accessibility Web Design</citetitle></ulink>,
				Royal National Institute for the Blind </para> 
		  </listitem> 
		  <listitem> 
			 <para> 
				<ulink url="http://www.utoronto.ca/atrc/rd/html/html.html"> 
				  <citetitle>Guide to Writing Accessible HTML</citetitle></ulink>, 
				Jan Richards </para> 
		  </listitem> 
		  <listitem> 
			 <para> 
				<ulink url="http://www.w3.org/TR/WAI-WEBCONTENT/"> 
				  <citetitle>Web Content Accessibility Guidelines
					 1.0</citetitle></ulink>, W3C Recommendation 5-May-1999 </para> 
		  </listitem> 
		</itemizedlist> </para> 
  </sect1> 
</chapter> 
