<preface id="preface"> 
  <title>Preface</title> 
  <para> The <emphasis>GNOME Documentation Style Guide</emphasis> provides
	 guidelines for authors who want to contribute to the GNOME Documentation
	 Project (GDP). </para> 
  <sect1 id="preface-1"> 
	 <title>About This Guide</title> 
	 <para> The goal of the GNOME Documentation Style Guide (GDSG) is to provide
		a framework for contributors to write good documentation. The GDSG also helps
		authors to write consistent documentation, so that users can expect certain
		structures and conventions in GNOME documents. </para> 
	 <para> This style guide discusses basic principles of clear, concise
		writing so that users can achieve the maximum benefit from GNOME documentation.
		The guide also provides standards for common terms and concepts. The guide
		provides recommendations rather than absolute rules. However, in all parts of
		the user interface, including documentation, consistency is a virtue. When you
		write GNOME documentation, try to follow these guidelines as closely as
		possible. Users benefit from the consistent application of the guidelines in
		this guide. </para> 
	 <para> This style guide is primarily for authors contributing documentation
		to the GDP in English. Although you can apply many of the guidelines in this
		book to all languages, there some guidelines that are specifically for
		English-language usage.</para> 
  </sect1> 
  <sect1 id="preface-2"> 
	 <title>What Is in This Guide</title> 
	 <para> This guide contains the following sections: </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="2.59*"/> 
		  <thead> 
			 <row rowsep="1"> 
				<entry colname="col1" rowsep="1" colsep="0" valign="top"
				 align="left"> 
				  <para> Section </para> </entry> 
				<entry colname="col2" rowsep="1" colsep="0" valign="top"
				 align="left"> 
				  <para> Summary </para> </entry> 
			 </row> 
		  </thead> 
		  <tbody> 
			 <row rowsep="0"> 
				<entry colname="col1" colsep="0" rowsep="0" valign="top"
				 align="left"> 
				  <para> <xref linkend="fundamentals"/> </para> </entry> 
				<entry colname="col2" rowsep="0" valign="top" align="left"> 
				  <para> Introduces basic concepts of technical documentation.
					 </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="infodesign"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Describes how to use different types of information
					 structures. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="grammar"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Provides advice and examples about how to use specific
					 parts of grammar. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="locale"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Provides guidelines to cater for the most common problems
					 encountered by translators of technical documentation. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="improving"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Outlines some tips about how you can review and improve
					 your writing. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="indexing"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Describes basic index requirements and indexing
					 techniques. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="gui-1"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Describes how to write about GNOME user interfaces.
					 </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="usability"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Discusses readability issues, and gives some ways to
					 assess readability. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="accessibility"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Discusses the needs of disabled users of technical
					 documentation. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="screenshots"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Provides style guidelines for screenshots. </para>
				  </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="legal-issues"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Covers essential legal topics in GNOME documentation.
					 </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="wordlist"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Provides a comprehensive list of agreed terminology for
					 use in GNOME documentation. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="units"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Provides a list of standard units that appear in GNOME
					 documentation, or in the GNOME Desktop. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="language"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Provides a list of unfamiliar language terms that are used
					 in this guide. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="infoblocks"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Provides examples of the information design building
					 blocks discussed in <xref linkend="infodesign"/>. </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" colsep="0" valign="top" align="left"> 
				  <para> <xref linkend="authorlist"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> Lists contributors to this guide. </para> </entry> 
			 </row> 
		  </tbody> 
		</tgroup> 
	 </informaltable> 
  </sect1> 
  <sect1 id="preface-3"> 
	 <title>Who Should Read This Guide</title> 
	 <para> Different parts of this guide are of different levels of interest to
		writers, depending on your level of experience, as shown in the following
		table. The key to the table is as follows: 
		<informaltable frame="none"> 
		  <tgroup cols="2" colsep="0" rowsep="0" align="left"><colspec colnum="1"
			 colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2"
			 colwidth="2.66*"/> 
			 <tbody> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> *</para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> You are probably familiar with this material. You only
						need to refer to this material for reference. </para> </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> ** </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> This information is of interest to you, however other
						parts of the guide are probably of more immediate interest. You can read these
						sections when you have time. </para> </entry> 
				</row> 
				<row> 
				  <entry colname="col1" valign="top" align="left"> 
					 <para> *** </para> </entry> 
				  <entry colname="col2" valign="top" align="left"> 
					 <para> This information is of immediate interest to you.
						</para> </entry> 
				</row> 
			 </tbody> 
		  </tgroup> 
		</informaltable> </para> 
	 <informaltable frame="topbot"> 
		<tgroup cols="3" colsep="0" rowsep="0" align="left"><colspec colnum="1"
		  colname="col1" colwidth="1.01*"/><colspec colnum="2" colname="col2"
		  colwidth="1.00*"/><colspec colname="col3" colnum="3" colwidth="1.00*"/> 
		  <thead> 
			 <row> 
				<entry colname="col1" rowsep="1" valign="top" align="left"> 
				  <para> Section </para> </entry> 
				<entry colname="col2" rowsep="1" valign="top" align="left"> 
				  <para> New Writers </para> </entry> 
				<entry colname="col3" rowsep="1" valign="top" align="left"> 
				  <para> Experienced Writers </para> </entry> 
			 </row> 
		  </thead> 
		  <tbody> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="fundamentals"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> *** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *</para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="infodesign"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> *** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *</para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="grammar"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> *** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="locale"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> *** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="improving"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> ** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> ** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="indexing"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> ** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> ** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="gui-1"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> ** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="usability"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> ** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> ** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="accessibility"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> ** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="screenshots"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> ** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="legal-issues"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> ** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> ** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="wordlist"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> *** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="units"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> *** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *** </para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="language"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> ** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *</para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="infoblocks"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> *** </para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *</para> </entry> 
			 </row> 
			 <row> 
				<entry colname="col1" valign="top" align="left"> 
				  <para> <xref linkend="authorlist"/> </para> </entry> 
				<entry colname="col2" valign="top" align="left"> 
				  <para> *</para> </entry> 
				<entry colname="col3" valign="top" align="left"> 
				  <para> *</para> </entry> 
			 </row> 
		  </tbody> 
		</tgroup> 
	 </informaltable> 
  </sect1> 
  <sect1 id="preface-4"> 
	 <title>Associated Documentation</title> 
	 <para> The following documentation is also associated with writing GNOME
		manuals: 
		<itemizedlist> 
		  <listitem> 
			 <para><ulink url="http://developer.gnome.org/projects/gdp/handbook.html"><citetitle>GNOME Handbook of Writing Software Documentation</citetitle></ulink> </para> 
		  </listitem> 
		  <listitem> 
			 <para> 
				<ulink url="http://developer.gnome.org/projects/gup/hig/1.0/"><citetitle>GNOME Human Interface Guidelines</citetitle></ulink>
				</para> 
		  </listitem> 
		</itemizedlist> </para> 
  </sect1> 
  <sect1 id="preface-5"> 
	 <title>Related Documentation</title> 
	 <para> See also the following documentation relevant to GNOME
		documentation: 
		<itemizedlist> 
		  <listitem> 
			 <para> 
				<ulink url="http://www.docbook.org/tdg/en/html/docbook.html"><citetitle>DocBook, The Definitive Guide</citetitle></ulink>, Norman Walsh and Leonard Muellner, O'Reilly &amp; Associates, Inc. </para> 
		  </listitem> 
		  <listitem> 
			 <para> 
				<ulink url="http://www.bartleby.com/141/"><citetitle>The Elements of Style</citetitle></ulink>, William
				Strunk Jr and E.B. White, The Macmillan Company </para> 
		  </listitem> 
		  <listitem> 
			 <para> 
				<ulink url="http://www.sun.com/books/catalog/edstyle/"><citetitle>Read Me First! A Style Guide for the Computer Industry</citetitle></ulink>, Sun Microsystems, SunSoft Press </para> 
		  </listitem> 
		</itemizedlist> </para> 
  </sect1> 
  <sect1 id="preface-6"> 
	 <title>Reference Sources</title> 
	 <para> The following reference sources are relevant to the guidelines in
		this guide: 
		<itemizedlist> 
		  <listitem> 
			 <para> 
				<ulink url="http://www.bartleby.com/61/"><citetitle>American Heritage Dictionary</citetitle></ulink>
				</para> 
		  </listitem> 
		  <listitem> 
			 <para> 
				<ulink
				url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"><citetitle>Chicago Manual of Style</citetitle></ulink></para> 
		  </listitem> 
		  <listitem> 
			 <para><ulink url="http://www.computer.org/author/style/cs-style.htm"><citetitle>IEEE Computer Society Style Guide</citetitle></ulink>
				</para> 
		  </listitem> 
		  <listitem> 
			 <para> 
				<ulink
				url="http://www.library.fordham.edu/res_guid/StyleGuide/StyleGuide.html#Guides%20OnLine"><citetitle>New York Public Library Writer's Guide to Style and
					 Usage</citetitle></ulink> and other style guides in print and online. </para> 
		  </listitem> 
		</itemizedlist> </para> 
  </sect1> 
</preface> 
