<chapter id="improving"> 
  <title>Ways to Improve Your Documentation</title> 
  <para> This chapter provides you with tips that can help you to improve the
	 readability and effectiveness of the documentation that you write. This chapter
	 does not describe how to troubleshoot the XML code in your document. </para> 
  <sect1 id="improving-1"> 
	 <title>Reviews</title> 
	 <para> Good reviews are the secret of good documentation. This section
		tells you about the different types of review that you can use during the
		development of documentation. In the ideal project, every item of documentation
		goes through each of the following reviews in the given order, and each review type is completed before the next review type is started. </para> 
	 <sect2 id="improving-2"> 
		<title>Technical Review</title> 
		<para> The developer is your main source of information for the products
		  that you write about. Use the developer as a source of expert knowledge to do
		  the following reviews: 
		  <itemizedlist> 
			 <listitem> 
				<para> Initial review of the first draft for technical accuracy and to ensure that all functionality is documented.
				  </para> 
			 </listitem> 
			 <listitem> 
				<para> Final technical verification review after you have
				  implemented all comments from other reviewers. </para> 
			 </listitem> 
		  </itemizedlist> </para> 
	 </sect2> 
	 <sect2 id="improving-3"> 
		<title>Peer Review</title> 
		<para> Make an agreement with a colleague writer to review your work. The
		  ideal conditions for a peer review are as follows: 
		  <itemizedlist> 
			 <listitem> 
				<para> The reviewer is not familiar with the product before the
				  review. </para> 
			 </listitem> 
			 <listitem> 
				<para> The reviewer reviews your documentation against the product
				  functionality to ensure that all descriptions and instructions are correct. </para> 
			 </listitem> 
		  </itemizedlist> </para> 
	 </sect2> 
	 <sect2 id="improving-4"> 
		<title>Editorial Review</title> 
		<para> An editorial review is essential. You should make a formal
		  arrangement for an editor to review your work. Allow plenty of time for an editorial
		  review, in advance of the date you plan to submit the documentation. </para> 
		<para> The editor checks the documentation against the agreed standards
		  that you use to write the documentation. The editor ensures that you have
		  followed general structural rules, for topics such as capitalization, spelling,
		  punctuation, and grammar. The editor also ensures that the documentation
		  adheres to specific rules such as terminology defined in
		  <xref linkend="wordlist"/>. </para> 
	 </sect2> 
	 <sect2 id="improving-5"> 
		<title>User Review</title> 
		<para> Ask someone who is not familiar with the product to try out the
		  product. Set a series of tasks for the user to complete. Instruct the user to
		  refer to the documentation during the execution of the tasks. This type of
		  review answers the following questions about the documentation: 
		  <itemizedlist> 
			 <listitem> 
				<para> How easily can users find relevant information? </para> 
			 </listitem> 
			 <listitem> 
				<para> How easily can users transfer information to the product?
				  </para> 
			 </listitem> 
			 <listitem> 
				<para> What user information is missing? </para> 
			 </listitem> 
		  </itemizedlist> If you need help setting up a user review, ask the
		  GNOME usability team, or another author who has done such a review. </para> 
                <note>
                  <para>Practicalities make a user review a rare treat, rather than an expected part of the documentation process.
                  </para>
                </note>
	 </sect2> 
	 <sect2 id="improving-5b"> 
		<title>Publication Review</title> 
		<para>Ask a colleague to have a quick glance through the document to ensure publication readiness.
                </para>
	 </sect2> 
  </sect1> 
  <sect1 id="improving-6"> 
	 <title>Checks You Can Do Yourself</title> 
	 <para> You can do a variety of checks on your writing during the
		development of your documentation, in the following areas. </para> 
	 <sect2 id="top-level-checks"> 
		<title>Top-Level Checks</title> 
		<para> You can perform the following top-level checks regularly during
		  documentation development: </para> 
		<itemizedlist> 
		  <listitem> 
			 <para> Wordcount </para> 
			 <para> As soon as a sentence or a procedure step starts to look
				suspiciously long, do a wordcount. See <xref linkend="fundamentals-2"/>,
				<emphasis>Golden Rule 1</emphasis>. </para> 
		  </listitem> 
		  <listitem> 
			 <para> Spellcheck </para> 
			 <para> Run regular spellchecks. Make sure that agreed terms from
				<xref linkend="wordlist"/> are in your spellchecker dictionary. </para> 
		  </listitem> 
		  <listitem> 
			 <para> Pronouns search </para> 
			 <para> Search for the following pronouns: </para> 
			 <itemizedlist> 
				<listitem> 
				  <para> It </para> 
				</listitem> 
				<listitem> 
				  <para> They </para> 
				</listitem> 
				<listitem> 
				  <para> Them </para> 
				</listitem> 
			 </itemizedlist> 
		  </listitem> 
		</itemizedlist> 
		<para> If you find any of the above pronouns, rewrite the sentences to
		  eliminate the pronoun. </para> 
	 </sect2> 
	 <sect2 id="top-ten-topics"> 
		<title>Top Ten Topics to Watch Out For</title> 
		<para> The following table lists the top ten topics that you need to
		  watch out for when you review your work, or when you perform a peer review for
		  a colleague. Review the documentation against the typical problem areas listed
		  in the table. The problem areas in the table are not exhaustive, you may
		  encounter more pitfalls during your review. The table provides you with cues so
		  that you can review your work with these topics and problem areas in mind. You
		  can find advice about how to deal with these topics in other sections of this
		  style guide. </para> 
		<informaltable frame="topbot"> 
		  <tgroup cols="2" align="left">
			 <colspec colname="col1" colwidth="0.32*" align="left"/>
			 <colspec colname="col2" colwidth="1.68*" align="left"/> 
			 <thead> 
				<row valign="top" rowsep="1"> 
				  <entry colname="col1" colsep="0" valign="top" align="left"> 
					 <para> Topic </para> </entry> 
				  <entry colname="col2" colsep="0" valign="top" align="left"> 
					 <para> Typical Problem Areas </para> </entry> 
				</row> 
			 </thead> 
			 <tbody> 
				<row valign="top"> 
				  <entry colname="col1" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> Accuracy </para> </entry> 
				  <entry colname="col2" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Functions differ from the description. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Functions are not described </para> 
						  </listitem> 
						  <listitem> 
							 <para> Functions are referred to using different
								terminology from the user interface. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Functions are described that do not exist. </para>
							 
						  </listitem> 
						  <listitem> 
							 <para> The description provides irrelevant and possibly
								confusing information. </para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row valign="top"> 
				  <entry colname="col1" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> Clarity </para> </entry> 
				  <entry colname="col2" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Ambiguous statements </para> 
						  </listitem> 
						  <listitem> 
							 <para> Inconsistency </para> 
						  </listitem> 
						  <listitem> 
							 <para> Unexplained events </para> 
						  </listitem> 
						  <listitem> 
							 <para> Undefined terms </para> 
						  </listitem> 
						  <listitem> 
							 <para> Vague, defensive language </para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row valign="top"> 
				  <entry colname="col1" colsep="0" rowsep="0" align="left"
					valign="top">Editorial</entry> 
				  <entry colname="col2" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Repeated words </para> 
						  </listitem> 
						  <listitem> 
							 <para> Misspelled words </para> 
						  </listitem> 
						  <listitem> 
							 <para> Typographical errors </para> 
						  </listitem> 
						  <listitem> 
							 <para> Missing words </para> 
						  </listitem> 
						  <listitem> 
							 <para> Verbs in the wrong tense </para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row valign="top"> 
				  <entry colname="col1" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> Grammar and Syntax </para> </entry> 
				  <entry colname="col2" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Tenses other than the present tense </para> 
						  </listitem> 
						  <listitem> 
							 <para> Long sentences joined by conjunctions, such as
								<emphasis> and</emphasis>. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Long sentences with confusing subordinate clauses
								</para> 
						  </listitem> 
						  <listitem> 
							 <para> Incomplete sentences that leave out the articles
								</para> 
						  </listitem> 
						  <listitem> 
							 <para> Over-elaborate sentence structure and syntax.
								</para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row valign="top"> 
				  <entry colname="col1" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> Graphics </para> </entry> 
				  <entry colname="col2" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Wrong graphic referred to in text. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Graphic has different features from the
								description. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Unnecessary use of formal figures. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Incorrect use of informal figures. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Graphics do not adhere to graphics style rules.
								</para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row valign="top"> 
				  <entry colname="col1" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> Information Design </para> </entry> 
				  <entry colname="col2" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Series of points are described in prose rather
								than an itemized list. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Sequences of actions are described in prose rather
								than a numbered list. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Topics are described in sequential paragraphs
								rather than in tables. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Information is ordered incorrectly within a
								document. </para> 
						  </listitem> 
						  <listitem> 
							 <para> Unclear or insufficient examples to support the
								descriptions. </para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row valign="top"> 
				  <entry colname="col1" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> Legal </para> </entry> 
				  <entry colname="col2" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Unsubstantiated claims </para> 
						  </listitem> 
						  <listitem> 
							 <para> Incorrect description of functions </para> 
						  </listitem> 
						  <listitem> 
							 <para> Insufficient notice of potential damage or hazard
								</para> 
						  </listitem> 
						  <listitem> 
							 <para> Statements about future features </para> 
						  </listitem> 
						  <listitem> 
							 <para> Statements about competing products </para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row valign="top"> 
				  <entry colname="col1" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> Punctuation </para> </entry> 
				  <entry colname="col2" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Use of slash, and
								<emphasis>and/or</emphasis></para> 
						  </listitem> 
						  <listitem> 
							 <para> Inconsistent use of hyphens and dashes</para> 
						  </listitem> 
						  <listitem> 
							 <para> Inappropriate use of parentheses and
								brackets</para> 
						  </listitem> 
						  <listitem> 
							 <para> Incorrect use of apostrophes</para> 
						  </listitem> 
						  <listitem> 
							 <para> Incorrect use of quotation marks</para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row valign="top"> 
				  <entry colname="col1" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> Style and Usage </para> </entry> 
				  <entry colname="col2" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Inconsistent capitalization </para> 
						  </listitem> 
						  <listitem> 
							 <para> Failure to use the terms in
								<xref linkend="wordlist"/> </para> 
						  </listitem> 
						  <listitem> 
							 <para> Use of terminology outside the 
								<ulink url="http://www.bartleby.com/61/"> 
								  <citetitle>American Heritage
									 Dictionary</citetitle></ulink> </para> 
						  </listitem> 
						  <listitem> 
							 <para> Inconsistent use of terminology </para> 
						  </listitem> 
						  <listitem> 
							 <para> Wordy explanations </para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
				<row valign="top"> 
				  <entry colname="col1" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> Tone </para> </entry> 
				  <entry colname="col2" colsep="0" rowsep="0" align="left"
					valign="top"> 
					 <para> 
						<itemizedlist> 
						  <listitem> 
							 <para> Jargon </para> 
						  </listitem> 
						  <listitem> 
							 <para> Colloquial language </para> 
						  </listitem> 
						  <listitem> 
							 <para> Humor </para> 
						  </listitem> 
						  <listitem> 
							 <para> Culture-specific references </para> 
						  </listitem> 
						  <listitem> 
							 <para> Gender-specific language </para> 
						  </listitem> 
						  <listitem> 
							 <para> Condescension </para> 
						  </listitem> 
						</itemizedlist> </para> </entry> 
				</row> 
			 </tbody> 
		  </tgroup> 
		</informaltable> 
	 </sect2> 
  </sect1> 
</chapter> 
