<chapter id="usability"> 
  <title>Usability and Readability Considerations for Technical
	 Documentation</title> 
  <para>
	 This chapter discusses the usability topics that you need to consider to
	 create effective technical documentation. This chapter also briefly discusses
	 readability tests for documentation. 
  </para>
  <sect1 id="usability-objectives"> 
	 <title>Usability Objectives</title> 
	 <para>
		The usability objectives for effective technical documentation are as
		follows: 
		<itemizedlist> 
		  <listitem> 
			 <para>
				Maximize speed of access to key information. 
			 </para>
		  </listitem> 
		  <listitem> 
			 <para>
				Present accurate and complete information. 
			 </para>
		  </listitem> 
		  <listitem> 
			 <para>
				Present specific information about specific topics. 
			 </para>
		  </listitem> 
		  <listitem> 
			 <para>
				Make the most effective use of the delivery method, for example,
				online Help. 
			 </para>
		  </listitem> 
		  <listitem> 
			 <para>
				Make the documentation the resource of choice for regular access,
				rather than, for example, asking colleagues how to perform actions. 
			 </para>
		  </listitem> 
		</itemizedlist> 
	 </para>
  </sect1> 
  <sect1 id="usability-non-objectives"> 
	 <title>Things You Are Not Trying to Do</title> 
	 <para>
		You also need to make sure that you do not inadvertently achieve the
		wrong objectives. For example: 
		<itemizedlist> 
		  <listitem> 
			 <para>
				Do not try to resolve inadequate interface design in the
				documentation.
			 </para>
		  </listitem> 
		  <listitem> 
			 <para>
				Do not try to fix functionality bugs in the documentation.
			 </para>
		  </listitem>
		  <listitem> 
			 <para>
				Do not distract from the task the user wants to perform.
			 </para>
		  </listitem> 
		</itemizedlist> 
	 </para>
  </sect1> 
  <sect1 id="usability-strategies"> 
	 <title>Strategies for Usability</title> 
	 <para>
		Strategies that maximize usability must do the following: 
		<itemizedlist> 
		  <listitem> 
			 <para>
				Reduce the burden on the short-term memory of the reader. Research
				shows that the average person can retain 7 ± 2 chunks of information in
				short-term memory. This does not necessarily mean that you must limit sentence
				lengths to seven words. You can group words together in familiar patterns to
				form single chunks of information. However, research also shows that a sentence
				length of more than 25 words overwhelms short-term memory. 
			 </para>
		  </listitem> 
		  <listitem> 
			 <para>
				Build understanding and recognition of terms and structures into
				long-term memory. Research shows that consistent usage is the best way to
				achieve this goal. The more information that the reader stores in long-term
				memory, the lower the burden on the short-term memory. 
			 </para>
		  </listitem> 
		  <listitem> 
			 <para>
				Provide clear navigation techniques. 
			 </para>
		  </listitem> 
		</itemizedlist>You can employ the following strategies to maximize the
		usability and readability of your documentation. 
	 </para>
	 <sect2 id="usability-superfluous"> 
		<title>Eliminate Superfluous Information</title> 
		<para>
		  Superfluous information gives rise to the following usability issues: 
		  <itemizedlist> 
			 <listitem> 
				<para>
				  Increases the amount of text that a reader has to understand
				  before reaching the required information. 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Increases the amount of time and effort that a reader has to
				  invest to access information. 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Takes up space in the short-term memory of the reader. 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Drains mental resources. The reader has a limited amount of
				  mental resources. The more mental resources that reading the documentation
				  takes up, the less mental resources are available for the reader to perform the
				  required actions. 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Introduces the potential for confusion. 
				</para>
			 </listitem> 
		  </itemizedlist>Examples of superfluous information are as follows: 
		  <itemizedlist> 
			 <listitem> 
				<para>
				  Unnecessary adjectives and adverbs 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Additional sentences that explain a concept in a slightly
				  different way 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Information about other topics that is not relevant 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Personal opinions 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Speculation about future product functions 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Rhetorical questions 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Over-exposed legal information 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Over-exposed author information 
				</para>
			 </listitem> 
		  </itemizedlist> 
		</para>
	 </sect2> 
	 <sect2 id="usability-consistent-structure"> 
		<title>Create Consistent Structures</title> 
		<para>
		  Create your documentation with repeated structures, using the same
		  hierarchy of sections and the same type of information in the sections. By
		  repeating the hierarchy of information structure throughout a documentation
		  set, you train the user to look for certain types of information in certain
		  places. 
		</para>
		<para>
		  The structure of the documentation is like a street map. Obviously, a
		  street map that is consistent across the whole of a city area is a better
		  navigation tool than a street map that is inconsistent. The intrinsic, repeated
		  structure of your document needs to feature all of the following
		  characteristics: 
		  <itemizedlist> 
			 <listitem> 
				<para>
				  Orderly 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Logical 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Consistent 
				</para>
			 </listitem> 
		  </itemizedlist> 
		</para>
	 </sect2> 
	 <sect2 id="usability-modular"> 
		<title>Use Modular Information Blocks</title> 
		<para>
		  Create modules that are short enough to reduce scrolling or
		  page-turning to a minimum. Aim to eliminate scrolling or page turning
		  completely for each individual module of information. 
		</para>
	 </sect2> 
	 <sect2 id="usability-consistent-language"> 
		<title>Use Consistent Language</title> 
		<para>
		  At school, teachers tell you to vary your writing so as to hold the
		  interest of the reader. Technical documentation requires the opposite approach.
		  Use the same vocabulary for the same purpose throughout your documentation.
		  Furthermore, when a team of writers work together, they must write with a
		  single voice. 
		</para>
		<para>
		  You expect the terminology in a street map to be the same for the whole
		  map. You do not expect particular areas of the map to have personalized
		  terminology. Similarly, use of consistent language by a team of writers across
		  the whole documentation set ensures that the reader is not confused by
		  conflicting terminology. 
		</para>
		<para>
		  Repeated use of consistent language builds long-term memory, and
		  therefore reduces the demand on short-term memory. The reader can access the
		  real information content of your text. 
		</para>
		<para>
		  Other language points that you need to consider: 
		  <itemizedlist> 
			 <listitem> 
				<para>
				  Research shows that words with Latin and Greek roots are harder
				  to understand than equivalent plain English words. 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Do not use non-English words, for example, Latin terms. Some
				  readers might not understand the non-English word. Even readers that do
				  understand the non-English word might need to pause and think about such a
				  word. 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Short words are easier to process in short-term memory than long
				  words. 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  The active voice is easier to understand than the passive voice. 
				</para>
			 </listitem> 
		  </itemizedlist>A major benefit from all writers in a documentation team
		  using consistent language, is that localization is made easier. Localized
		  versions of documentation add another dimension to documentation usability. 
		</para>
	 </sect2> 
	 <sect2 id="usability-consistent-typographic"> 
		<title>Use Consistent Typographic Conventions</title> 
		<para>
		  Where documentation structure is like a street map, typographic
		  conventions are like street signs and road markings. Typographic conventions
		  such as capitalization rules, punctuation, and emphasis tell readers what to
		  expect. Consistent typographic conventions provide the inner structure of a
		  documentation set. Inconsistent typographic conventions confuse and distract
		  the reader. 
		</para>
		<para>
		  Imagine the confusion if one area of a city uses different street signs
		  and road markings than other areas. Or worse, imagine the chaos if one area of
		  a city uses the same road markings as everywhere else, but to mean different
		  things. No-one is in danger from inconsistent typographical conventions in a
		  manual, however readers might not revisit the documentation if the conventions
		  are confusing. 
		</para>
	 </sect2> 
  </sect1> 
  <sect1 id="usability-readability"> 
	 <title>Readability Tests</title> 
	 <para>
		The main function of readability tests is to give you a quick assessment
		about the density of your writing. Readability tests cannot tell you how easily
		a reader can understand the information in the text. 
	 </para>
	 <para>
		You can perform readability tests manually by counting and doing a
		mathematical calculation, or by using word-processing software. There are
		several popular readability indexes, for example: 
		<itemizedlist> 
		  <listitem> 
			 <para>
				Gunning Fog Index 
			 </para>
		  </listitem> 
		  <listitem> 
			 <para>
				Flesch Reading Ease Scale 
			 </para>
		  </listitem> 
		  <listitem> 
			 <para>
				Flesch-Kincaid Grade Index 
			 </para>
		  </listitem> 
		</itemizedlist> 
	 </para>
	 <sect2 id="usability-fog-index"> 
		<title>Gunning Fog Index</title> 
		<para>
		  To calculate the Gunning Fog Index of a passage, do the following: 
		  <orderedlist> 
			 <listitem> 
				<para>
				  Count the number of words in the paragraph: W 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Count the number of sentences in the paragraph: S 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Count the number of words of three syllables or more: T 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Apply the following formula: [W/S + T/(Wx100)] x 0.4 
				</para>
			 </listitem> 
		  </orderedlist>The Gunning Fog Index gives the number of years of
		  education that your reader needs to understand the paragraph. Typically, in
		  technical documentation, aim for a Gunning Fog Index between 10 and 15. The
		  Gunning Fog Index formula implies that short sentences written in plain English
		  achieve a better score than long sentences written in complicated language. 
		</para>
	 </sect2> 
	 <sect2 id="usability-flesch"> 
		<title>Flesch Reading Ease Scale</title> 
		<para>
		  Calculate the readability of a passage on the Flesch Reading Ease Scale
		  in the following way: 
		  <orderedlist> 
			 <listitem> 
				<para>
				  Calculate the average sentence length: L 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Calculate the average number of syllables per word: N 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Calculate the score between 0 and 00%. 
				</para>
			 </listitem> 
		  </orderedlist> 
		</para>
		<para>
		  The higher the score, the easier the text is to understand. Aim to
		  maximize the score. The Flesch Reading Ease Scale measures readability as
		  follows: 
		</para>
		<informaltable frame="none"> 
		  <tgroup cols="3" colsep="0" rowsep="0"><colspec colnum="1"
			 colname="col1" colwidth="*"/><colspec colnum="2" colname="col2"
			 colwidth="*"/><colspec colnum="3" colname="col3" colwidth="*"/> 
			 <tbody> 
				<row> 
				  <entry colname="col1"> 
					 <para>
						100 
					 </para>
				  </entry> 
				  <entry colname="col2"> 
					 <para>
						Very easy to read. 
					 </para>
				  </entry> 
				  <entry colname="col3"> 
					 <para>
						Average sentence length is 12 words or less. No words of more
						than two syllables. 
					 </para>
				  </entry> 
				</row> 
				<row> 
				  <entry colname="col1"> 
					 <para>
						65 
					 </para>
				  </entry> 
				  <entry colname="col2"> 
					 <para>
						Plain English. 
					 </para>
				  </entry> 
				  <entry colname="col3"> 
					 <para>
						Average sentence length is 15 to 20 words. Average word has
						two syllables. 
					 </para>
				  </entry> 
				</row> 
				<row> 
				  <entry colname="col1"> 
					 <para>
						0</para>
				  </entry> 
				  <entry colname="col2"> 
					 <para>
						Extremely difficult to read. 
					 </para>
				  </entry> 
				  <entry colname="col3"> 
					 <para>
						Average sentence length is 37 words. Average word has more
						than two syllables. 
					 </para>
				  </entry> 
				</row> 
			 </tbody> 
		  </tgroup> 
		</informaltable> 
		<para>
		  Click on the following link to find out more about the 
		  <ulink
			url="http://www.mang.canterbury.ac.nz/courseinfo/AcademicWriting/Flesch.htm">
			 Flesch Readability Test</ulink>. In this link, Rudolf Flesch, the developer of
		  the test, provides some background information. 
		</para>
	 </sect2> 
	 <sect2 id="usability-flesch-kincaid"> 
		<title>Flesch-Kincaid Index</title> 
		<para>
		  This index computes readability based on the average number of
		  syllables per word and the average number of words per sentence. The score
		  indicates the number of years of combined primary and secondary education that
		  a reader needs to understand a text. For example, a score of 8.0 means that you
		  can understand the text after eight years of combined primary and secondary
		  education. Standard writing achieves around 7.0 to 8.0 on the Flesch-Kincaid
		  Index. 
		</para>
		<para>
		  Click on the following link to find out more about the 
		  <ulink url="http://www.timetabler.com/reading.html"> Flesch-Kincaid
			 Index and other readability tests</ulink>. Although this web page deals with
		  textbooks, you can also apply the concepts to technical documentation. 
		</para>
	 </sect2> 
  </sect1> 
</chapter> 
