<!-- =================== INDEXING Original author Pat 
Costello ================= -->
<chapter id="indexing"> 
  <title>Indexing Your Documentation</title> 
  <para>
	 This chapter provides you with tips that can help you to effectively index
	 your documentation. 
  </para>
  <sect1 id="indexing-1"> 
	 <title>Index Essentials</title> 
	 <para>
		An index helps users to find the information they need in the
		documentation that you write. A good index records every pertinent statement in
		the body of the text. The subject matter and purpose of each section in your
		book determine which statements are pertinent and which are peripheral.
		Deciding which statements are pertinent is a judgment call, and the task that
		causes most difficulty for writers. These guidelines help you to recognize and
		label statements for an index. 
	 </para>
	 <sect2 id="indexing-2"> 
		<title>Topics to Index</title> 
		<para>
		  Consider the following points when you look for pertinent statements to
		  index: 
		  <itemizedlist> 
			 <listitem> 
				<para>
				  A pertinent statement can be a single phrase, a sentence, a
				  paragraph, or even several pages. 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Begin the search for pertinent statements in the first paragraph
				  of the main body of your manual. 
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Conclude your search for pertinent statements on the last page of
				  the last appendix.
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Do not index the front matter.
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Indexing the glossary can provide a useful source of information
				  for the user but is not essential, especially for manuals that appear in print
				  as well as online.
				</para>
			 </listitem> 
		  </itemizedlist> 
		</para>
		<para>
		  Statements that refer to the following topics are often pertinent for
		  an index: 
		  <itemizedlist> 
			 <listitem> 
				<para>
				  Definitions
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Restrictions
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Acronyms
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Commands
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Command qualifiers
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Routines
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Data structures
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Key functions
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Procedures and tasks
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Tips, notes, and cautions
				</para>
			 </listitem> 
			 <listitem> 
				<para>
				  Examples, tables, and figures
				</para>
			 </listitem> 
		  </itemizedlist> 
		</para>
	 </sect2> 
	 <sect2 id="indexing-3"> 
		<title>How to Compose Index Entries</title> 
		<para>
		  When you identify a pertinent statement, you need to flag the statement
		  in a way that alerts the user to the information. This flag is the index entry.
		  When you compose an index entry, you must first determine the topics that
		  relate to the statement. These topics become the primary entries. Next, you
		  must determine the nature of the information in the statement relating to each
		  topic. These descriptions become the secondary entries.
		</para>
		<sect3 id="indexing-4"> 
		  <title>Primary Entries</title> 
		  <para>
			 Make your primary entries precise, logical, and consistent with the
			 terminology in the rest of the documentation set. Some tips: 
			 <itemizedlist> 
				<listitem> 
				  <para>
					 Make your primary entries nouns or a noun phrase that a user
					 might look for. For example: 
				  </para>
	 <informaltable frame="topbot"> 
		<tgroup cols="2" colsep="0" rowsep="0" align="left"><colspec
		  colwidth="2.50*" align="left"/><colspec colwidth="2.50*" align="left"/> 
		  <tbody> 
			 <row valign="top"> 
				<entry align="left" valign="top"> 
				  <para>Applications</para> </entry> 
				<entry align="left" valign="top"> 
				  <para>Noun.</para> </entry> 
			 </row> 
			 <row valign="top"> 
				<entry align="left" valign="top"> 
				  <para>Starting applications </para> </entry> 
				<entry align="left" valign="top"> 
				  <para>Noun phrase.</para> </entry> 
			 </row> 
		  </tbody> 
		</tgroup> 
	 </informaltable> 
				</listitem> 
				<listitem> 
				  <para>
					 Do not use verbs or adjectives standing alone, because users
					 are unlikely to search for these words. 
				  </para>
				</listitem> 
				<listitem> 
				  <para>
					 Make sure that the term used for the primary entry appears on
					 the page to which the index points. 
				  </para>
				</listitem> 
			 </itemizedlist> 
		  </para>
		</sect3> 
		<sect3 id="indexing-5"> 
		  <title>Subentries</title> 
		  <para>
			 A subentry is a verb, phrase, or adjective that describes the nature
			 of the information about a topic. You can also use nouns and noun phrases for
			 subentries. For example: 
			 <variablelist> 
				<varlistentry> 
				  <term>Applications</term> 
				  <listitem> 
					 <para>
						menu 
					 </para>
					 <para>
						starting from menu 
					 </para>
					 <para>
						starting from command line 
					 </para>
				  </listitem> 
				</varlistentry> 
			 </variablelist> 
		  </para>
		  <para>
			 See the 
			 <ulink url="http://developer.gnome.org/projects/gdp/handbook.html"> 
				<citetitle>GNOME Handbook of Writing Software
				  Documentation</citetitle></ulink>, <emphasis>Indexing</emphasis> for more
			 examples of index subentries. 
		  </para>
		</sect3> 
	 </sect2> 
	 <sect2 id="indexing-6"> 
		<title>Index Navigation</title> 
		<para>
		  You can use the following types of cross-references to help users to
		  navigate the index: 
		  <variablelist> 
			 <varlistentry> 
				<term>See</term> 
				<listitem> 
				  <para>
					 Use this cross-reference to point from a synonym to the term
					 under which the user can find the index entries. 
				  </para>
				</listitem> 
			 </varlistentry> 
		  </variablelist> 
		  <variablelist> 
			 <varlistentry> 
				<term>See also</term> 
				<listitem> 
				  <para>
					 Use this cross-reference to point the user to topics that are
					 related to the original entry. 
				  </para>
				</listitem> 
			 </varlistentry> 
		  </variablelist> 
		</para>
	 </sect2> 
  </sect1> 
  <sect1 id="indexing-7"> 
	 <title>How to Evaluate Your Index</title> 
	 <para>
		When you create an index for a manual, you need to check the index for
		the following attributes: 
		<itemizedlist> 
		  <listitem> 
			 <para>
				Balance and structure 
			 </para>
		  </listitem> 
		  <listitem> 
			 <para>
				Clarity and consistency 
			 </para>
		  </listitem> 
		</itemizedlist> 
	 </para>
	 <sect2 id="indexing-8"> 
		<title>Balance and Structure</title> 
		<para>
		  Check the index for the following common problems: 
		  <variablelist> 
			 <varlistentry> 
				<term>Overloaded primary entries</term> 
				<listitem> 
				  <para>
					 If you find that a small number of primary entries in your
					 index have a large number of subentries, try to find other labels for some of
					 the subentries. Try to keep the number of subentries to a useful level.
				  </para>
				</listitem> 
			 </varlistentry> 
			 <varlistentry> 
				<term>Inadequate subentry labels</term> 
				<listitem> 
				  <para>
					 If your subentry labels are too cryptic, for example just page
					 numbers, then the reader does not have enough pointers to decide where to go in
					 the book for the required information. 
				  </para>
				</listitem> 
			 </varlistentry> 
			 <varlistentry> 
				<term>Unbalanced entries across the book</term> 
				<listitem> 
				  <para>
					 If one or two chapters in the book are heavily represented in
					 the index, then you need to look at the indexing frequency in the other
					 chapters. Also, you might want to look at the overall information design
					 structure of your book, to see if you really need those other chapters. 
				  </para>
				</listitem> 
			 </varlistentry> 
		  </variablelist> 
		</para>
	 </sect2> 
	 <sect2 id="indexing-9"> 
		<title>Clarity and Consistency</title> 
		<para>
		  To check the index for clarity and consistency, perform the following
		  actions: 
		  <variablelist> 
			 <varlistentry> 
				<term>Ensure that all primary entries are nouns</term> 
				<listitem> 
				  <para>
					 Look through your index for primary entries that are verbs and
					 adjectives. Replace the verbs and adjectives with nouns or noun phrases. 
				  </para>
				</listitem> 
			 </varlistentry> 
			 <varlistentry> 
				<term>Clarify the relationship between primary entries and
				  subentries</term> 
				<listitem> 
				  <para>
					 Make sure that the subentries bear a meaningful relationship to
					 the primary entries. 
				  </para>
				</listitem> 
			 </varlistentry> 
			 <varlistentry> 
				<term>Correlate primary entries and subentries</term> 
				<listitem> 
				  <para>
					 Make sure that related subentries are all gathered together
					 under the same primary entries. 
				  </para>
				</listitem> 
			 </varlistentry> 
		  </variablelist> 
		</para>
	 </sect2> 
  </sect1> 
  <sect1 id="indexing-10"> 
	 <title>When to Index GNOME Documentation</title> 
	 <para>
		When you want to index a manual, you need to consider the type of
		documentation: 
		<variablelist> 
		  <varlistentry> 
			 <term>Online Help</term> 
			 <listitem> 
				<para>
				  As <application>Scrollkeeper</application> is still a product in
				  development, the use of indexing is not yet clear. Until the situation
				  clarifies, you only need to put a single index entry into each online Help
				  manual to create a primary entry for the application name. The template for the
				  online Help manuals provides an example of where to create the index entry in
				  the online Help manual. When the role and function of
				  <application>Scrollkeeper</application> becomes clearer, writers can apply more
				  of the indexing principles outlined in this chapter. 
				</para>
				<para>
				  You can find out more about the templates in the 
				  <ulink
					url="http://developer.gnome.org/projects/gdp/handbook.html"> 
					 <citetitle>GNOME Handbook for Writing Software
						Documentation</citetitle></ulink>. 
				</para>
			 </listitem> 
		  </varlistentry> 
		  <varlistentry> 
			 <term>Printed manuals</term> 
			 <listitem> 
				<para>
				  Apply the indexing principles outlined in this chapter to printed
				  manuals.
				</para>
			 </listitem> 
		  </varlistentry> 
		</variablelist> 
	 </para>
  </sect1> 
</chapter>