<chapter id="fundamentals"> 
  <title>Fundamental Concepts of Technical Documentation</title> 
  <para> This chapter provides a brief introduction to writing technical
	 documentation. </para> 
  <sect1 id="fundamentals-1"> 
	 <title>General Style Requirements</title> 
	 <para> Technical writing for computer applications imposes special
		constraints beyond the basic requirements of good prose. Good technical
		documentation has the following characteristics: </para> 
	 <variablelist> 
		<varlistentry> 
		  <term> Comprehensive</term> 
		  <listitem> 
			 <para> Describe all of the functionality of a product. Do not omit
				functionality that you regard as irrelevant for the user. </para> 
		  </listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term> Conformant</term> 
		  <listitem> 
			 <para> Describe what you see. Do not describe what you want to see.
				Present your information in the order that users experience the subject matter.
				</para> 
		  </listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term> Clear</term> 
		  <listitem> 
			 <para> Read 
				<ulink url="http://www.bartleby.com/141/"> 
				  <citetitle>The Elements of Style</citetitle></ulink> to help make
				your writing clear. </para> 
		  </listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term> Consistent</term> 
		  <listitem> 
			 <para> Use agreed vocabulary throughout your documentation. Use the
				same vocabulary as other writers who are working on related documentation.
				</para> 
		  </listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Concise</term> 
		  <listitem> 
			 <para> Review your work frequently as you write your document. Ask
				yourself which words you can take out. See <xref linkend="fundamentals-2"/> for
				a specific guideline. </para> 
		  </listitem> 
		</varlistentry> 
	 </variablelist> 
  </sect1> 
  <sect1 id="fundamentals-2"> 
	 <title>Golden Rules</title> 
	 <para> This section contains some basic style guidelines. Subsequent
		chapters of this book expand on these guidelines to give more detailed
		guidance. </para> 
	 <para> 
		<informaltable frame="topbot"> 
		  <tgroup cols="2" colsep="0" rowsep="0"><colspec colnum="1"
			 colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2"
			 colwidth="511.50pt"/> 
			 <tbody> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Golden Rule 1 </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Limit each sentence to less than 25 words. </para>
							 
						  </listitem> 
						</itemizedlist> 
						<itemizedlist> 
						  <listitem> 
							 <para> Limit each procedure step to 23 words. </para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Example </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> Under normal operating conditions, the kernel does not
						always immediately write file data to the disks, storing it in a memory buffer
						and then periodically writing to the disks to speed up operations. </para>
					 </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Rewrite </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> Normally, the kernel stores the data in memory prior to
						periodically writing the data to the disk. </para> </entry> 
				</row> 
			 </tbody> 
		  </tgroup> 
		</informaltable> </para> 
	 <para> 
		<informaltable frame="topbot"> 
		  <tgroup cols="2" colsep="0" rowsep="0"><colspec colnum="1"
			 colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2"
			 colwidth="512.25pt"/> 
			 <tbody> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Golden Rule 2 </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Limit each paragraph to one topic. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Limit each sentence to one idea. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Limit each procedure step to one action. </para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Example </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> The <application>Workspace Switcher</application> applet
						helps you navigate all of the virtual desktops available on your system. The X
						Window system, working in hand with a piece of software called a
						<emphasis>window manager</emphasis>, allows you to create more than one virtual
						desktop, known as <emphasis>workspaces</emphasis>, to organize your work, with
						different applications running in each workspace. The <application>Workspace
						Switcher</application> applet is a navigational tool to get around the various
						workspaces, providing a miniature road map in the GNOME panel showing all your
						workspaces and allowing you to switch easily between them. </para> </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Rewrite </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> You can use the <application>Workspace
						Switcher</application> to add new <emphasis>workspaces</emphasis> to the GNOME 
						Desktop. You can run different applications in each workspace. The
						<application>Workspace Switcher</application> applet provides a miniature map
						that shows all of your workspaces. You can use the <application>Workspace
						Switcher</application> applet to switch between workspaces. </para> </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Tip </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> Plan the order of paragraphs before you start writing.
						Decide which topic you want to cover in each paragraph. </para> </entry> 
				</row> 
			 </tbody> 
		  </tgroup> 
		</informaltable> </para> 
	 <para> 
		<informaltable frame="topbot"> 
		  <tgroup cols="2" colsep="0" rowsep="0"><colspec colnum="1"
			 colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2"
			 colwidth="512.25pt"/> 
			 <tbody> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Golden Rule 3 </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> Use explicit examples to demonstrate how an application
						works. Provide instructions rather than descriptions. </para> </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Example </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> There is a text box that you can use to find out the
						definition of a word. </para> </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Rewrite </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> To request a definition of a word, type the word in the
						text box, then click on the Lookup button. </para> </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Tip </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> Do not apply this guideline too rigidly. Sometimes you
						must explain how software works to support your how-to examples. </para>
					 </entry> 
				</row> 
			 </tbody> 
		  </tgroup> 
		</informaltable> </para> 
	 <para> 
		<informaltable frame="topbot"> 
		  <tgroup cols="2" colsep="0" rowsep="0"><colspec colnum="1"
			 colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2"
			 colwidth="514.50pt"/> 
			 <tbody> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Golden Rule 4 </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> Write in a neutral tone. </para> </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Example </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> The applet is a handy little screen grabber. </para>
					 </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> Rewrite </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> You use the applet to take screenshots. </para> </entry>
				  
				</row> 
			 </tbody> 
		  </tgroup> 
		</informaltable> </para> 
  </sect1> 
  <sect1 id="fundamentals-3"> 
	 <title>Tone</title> 
	 <para> Inappropriate tone can hinder reader access to information. A
		neutral tone free of opinion or personal flavor reduces the processing load for
		the reader to understand the information. Another benefit of a neutral tone is
		that several writers can work in parallel on a large technical documentation
		project. Furthermore, different writers can join the project at different
		times. The use of a neutral tone helps to achieve consistency across a
		documentation set, and thereby facilitates user access to information. The best
		way to achieve a common, neutral tone is to apply the following principles: 
		<variablelist> 
		  <varlistentry> 
			 <term>Avoid humor</term> 
			 <listitem> 
				<para> Humor distracts from the information you are trying to
				  provide. Humor also makes documentation difficult to translate. Stay factual.
				  </para> 
			 </listitem> 
		  </varlistentry> 
		  <varlistentry> 
			 <term>Avoid personal opinions</term> 
			 <listitem> 
				<para> Whether you think a function is useful or woeful is
				  irrelevant. Report the function to the user, with instructions about how to use
				  the function. Stay accurate. </para> 
			 </listitem> 
		  </varlistentry> 
		  <varlistentry> 
			 <term>Avoid colloquial language</term> 
			 <listitem> 
				<para> Colloquial language is difficult to translate and usually
				  culture-specific. Stay neutral. </para> 
			 </listitem> 
		  </varlistentry> 
		  <varlistentry> 
			 <term>Avoid topical expressions</term> 
			 <listitem> 
				<para> An expression that is in common use today might convey
				  something completely different tomorrow. Stay technical. </para> 
			 </listitem> 
		  </varlistentry> 
		  <varlistentry> 
			 <term>Avoid aspirational statements</term> 
			 <listitem> 
				<para> Statements about the future developments of a product do not
				  belong in technical documentation. Write about what you see right now. Stay
				  real. </para> 
			 </listitem> 
		  </varlistentry> 
		</variablelist> </para> 
  </sect1> 
  <sect1 id="fundamentals-4"> 
	 <title>Reaching the Right Audience</title> 
	 <para> All of the decisions that you make about the structure and content
		of a manual follow from an understanding of the audience. You need to think
		about how the audience accesses the documentation, what sort of information the
		audience needs, and the experience level of the audience. Usually, you need to
		create documentation that is suitable for different audiences. The following
		sections introduce some of the audience-related topics you need to consider.
		</para> 
	 <sect2 id="fundamentals-6"> 
		<title>User Motivation</title> 
		<para> Do not waste the time of the user who looks for information in
		  your documentation. Users do not read technical documentation for
		  entertainment. Users usually have specific questions. You need to give clear
		  answers to those questions. </para> 
	 </sect2> 
	 <sect2 id="fundamentals-7"> 
		<title>New Users</title> 
		<para> New users to the GNOME Desktop are likely to consult online Help
		  for guidance about unfamiliar applications or functionality. Each Help manual
		  should contain enough introductory information to tell new users how to start
		  using the application. Each Help manual should also contain enough usage
		  instructions to tell users the different actions that they can perform with the
		  application. Keep these instructions task-oriented. You do not need to describe
		  GUI screens, dialogs, and dialog elements in Help, unless there is an unusual
		  feature that affects your instructions. </para> 
	 </sect2> 
	 <sect2 id="fundamentals-8"> 
		<title>Experienced Users</title> 
		<para> Experienced users are more likely to use documentation as a
		  reference. The documentation therefore needs to be complete, well-organized,
		  and in the case of printed manuals, well-indexed. </para> 
	 </sect2> 
	 <sect2 id="fundamentals-9"> 
		<title>Do Not Offend Your Audience</title> 
		<para> To avoid offending your readers, apply the following guidelines to
		  your documentation: 
		  <variablelist> 
			 <varlistentry> 
				<term>Avoid insider language</term> 
				<listitem> 
				  <para> Insider language includes both undefined jargon and the
					 tendency of the computer community to shorten words. For example, use the term
					 <emphasis>documentation</emphasis> instead of the term
					 <emphasis>docs</emphasis>. You can identify jargon if terminology fails the
					 following conditions: 
					 <itemizedlist> 
						<listitem> 
						  <para> A term does not appear in <xref
							 linkend="wordlist"/>, in this guide. </para> 
						</listitem> 
						<listitem> 
						  <para> A term does not appear in the 
							 <ulink url="http://www.bartleby.com/61/"> 
								<citetitle>American Heritage
								  Dictionary</citetitle></ulink>. </para> 
						</listitem> 
						<listitem> 
						  <para> A term does not appear in the glossary of the manual
							 that you are writing. </para> 
						</listitem> 
						<listitem> 
						  <para> A term is not defined in the body text of the manual
							 that you are writing. </para> 
						</listitem> 
					 </itemizedlist> </para> 
				</listitem> 
			 </varlistentry> 
			 <varlistentry> 
				<term>Avoid sexist language</term> 
				<listitem> 
				  <para> Pronoun constructions such as <emphasis>his/her</emphasis>
					 or <emphasis>s/he</emphasis> do not exist. There is no need to identify gender
					 in your instructions. </para> 
				</listitem> 
			 </varlistentry> 
			 <varlistentry> 
				<term>Avoid culture-specific language</term> 
				<listitem> 
				  <para> There is little point in giving an example that everyone
					 in your town knows about, but is a complete mystery to everyone else in the
					 world. </para> 
				</listitem> 
			 </varlistentry> 
			 <varlistentry> 
				<term>Avoid talking down to your reader</term> 
				<listitem> 
				  <para> There are few experiences more irritating for a user than
					 documentation that says an action is easy or quick, when in fact the user
					 cannot complete the action. Do not qualify or prejudge actions. </para> 
				</listitem> 
			 </varlistentry> 
		  </variablelist> </para> 
		<para> Other parts of this guide discuss in more detail tone and language
		  usage that can cause offense. </para> 
	 </sect2> 
  </sect1> 
  <sect1 id="fundamentals-5"> 
	 <title>Structure</title> 
	 <para> Good organization goes a long way towards creating good
		documentation. You need to consider the type of manual that you want to create
		before you start work. Not every manual can follow the same structure. You must
		break up a complex, multifunction application such as
		<application>Evolution</application> into many parts, to provide detailed
		explanations of the separate functional modules. An applet, on the other hand,
		needs a brief description of the GUI, basic usage instructions, and details on
		any necessary preferences. </para> 
	 <sect2 id="fundamentals-10"> 
		<title>Help Manuals</title> 
		<para> Wherever possible, use templates to ensure that your Help manual
		  follows a standard approach. You can find templates for Help manuals in the 
		  <ulink
			url="http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/"> 
			 <citetitle>GNOME Handbook of Writing Software
				Documentation</citetitle></ulink>.</para> 
	 </sect2> 
	 <sect2 id="fundamentals-11"> 
		<title>Guides</title> 
		<para> If you need to write a guide about a large application or a set of
		  applications, then the book is substantially longer than a Help manual. You
		  need to develop an outline plan for your guide. The precise composition of your
		  manual depends on the subject, however in general you need the following book
		  components: </para> 
		<variablelist> 
		  <varlistentry> 
			 <term>Front matter</term> 
			 <listitem> 
				<para> Defines the function of the book. Includes navigation aids
				  to the remaining sections of the book, such as a table of contents, or links.
				  This section might contain a Preface. </para> 
			 </listitem> 
		  </varlistentry> 
		  <varlistentry> 
			 <term>Introduction</term> 
			 <listitem> 
				<para> Explains the application to new users. You should provide an
				  expanded definition of the function of the application, built around
				  illustrations and examples. </para> 
			 </listitem> 
		  </varlistentry> 
		  <varlistentry> 
			 <term>Document body</term> 
			 <listitem> 
				<para> Consists of several sections or chapters that provide a more
				  detailed explanation of how to use the application. This is where you achieve
				  completeness, telling the user how to complete all the main tasks associated
				  with the application. Chapter headings are usually descriptive of the each
				  topic area. Sub-headings within the chapter are usually task-oriented, so that
				  users can quickly find information about a specific action within the topic
				  area. </para> 
			 </listitem> 
		  </varlistentry> 
		  <varlistentry> 
			 <term>Glossary</term> 
			 <listitem> 
				<para> Defines specific terms in the book. You do not need to
				  define terms that are in the 
				  <ulink url="http://www.bartleby.com/61/"> 
					 <citetitle>American Heritage
						Dictionary</citetitle></ulink>.</para> 
			 </listitem> 
		  </varlistentry> 
		  <varlistentry> 
			 <term>Appendices</term> 
			 <listitem> 
				<para> Contain additional notes about related topics that are not
				  directly explained in the document body. </para> 
			 </listitem> 
		  </varlistentry> 
		  <varlistentry> 
			 <term>Index</term> 
			 <listitem> 
				<para> Provides keyword links to specific concepts in the book.
				  Follow the guidelines in this guide to create an effective index. </para> 
			 </listitem> 
		  </varlistentry> 
		</variablelist> 
	 </sect2> 
  </sect1> 
</chapter> 
