path: root/en_US/style.xml

<!-- $Id: -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;

]>


<chapter id="ch-style">
 
  <title>Style</title>

  <para>
    Writing good technical documentation is not simply reproducing
    command lines and instruction sets.  Good documentation is easy to
    read, understand, and translate, and presents a concise logical
    progression of concepts.  Good documentation can also be defined by
    what it does <emphasis>not</emphasis> contain.  Your tutorial should
    avoid:
  </para>
  <itemizedlist>
    <listitem>
      <para>
        Excessive wordiness
      </para>
    </listitem>
    <listitem>
      <para>
        Unnecessary or undefined jargon
      </para>
    </listitem>
    <listitem>
      <para>
        Grammatical or spelling errors
      </para>
    </listitem>
    <listitem>
      <para>
        References to yourself or your experiences
      </para>
    </listitem>
    <listitem>
      <para>
        Remarks which might offend or confuse any reader
      </para>
    </listitem>
  </itemizedlist>
  <para>
    This chapter contains style rules and guidelines for writing &FED;
    documentation.  Guidelines are not the same as rules.  It is
    acceptable to violate a guideline when it makes your material easier
    to understand.  Follow guidelines whenever possible, but follow
    rules at all times.  Assume any advice is a guideline unless
    identified otherwise.
  </para>

  <section id="sn-intro-to-style">
     
    <title>Why Style Is Important</title>
     
    <para>
      Writing well comes naturally to almost no one.  It is a skill that
      professional writers, even famous ones, must practice constantly.
      <firstterm>Style</firstterm>
      <indexterm><primary>style</primary></indexterm> is the quality
      that separates elegant writing from the merely functional.
    </para>
    <para>
      Elegance comes in many forms.  In prose and poetry, elegant
      writing may not follow some (or any) common rules of grammar,
      syntax, or spelling.  A good example is Episode 18, "Penelope," in
      James Joyce's novel <citetitle>Ulysses</citetitle><footnote
	id='fn-ulysses'>
        <para>
          For example, refer to. <ulink
	    url="http://www.online-literature.com/james_joyce/ulysses/18/">http://www.online-literature.com/james_joyce/ulysses/18/</ulink>. 
	  Please note that this example contains some mature themes and
	  language, and is not suitable for all readers.
        </para>
      </footnote>.  There, Joyce uses long streams of words without
      punctuation to simulate a character's internal consciousness.  By
      violating basic rules of grammar and syntax, Joyce simulates the
      disorganized but loosely connected thought patterns of the
      narrator.
    </para>
    <para>
      Technical documentation, however, should always respect these
      rules.  The more a document departs from standard language usage,
      the more difficult the material becomes for the reader.  For
      example, readers may not be native speakers of the language used,
      or they might be reading a translation.  If the writer uses slang,
      idioms, or jargon, a reader or translator may easily become
      confused.  The following example compares two different written
      executions of the same idea:
    </para>
    <example>
      <title>Incorrect style</title>

	<!-- I prefer "incorrect," because I think terms such as
	"problematic" are mealy-mouthed.  They remind me of the late
	1980's English textbook trend toward the politically correct yet
	wholly unhelpful "standard/nonstandard."  But then, I tend to be
	dogmatic; it's probably my Catholic upbringing. [PWF] -->

      <para>
        So you made the changes I showed you in the last section. What's
	the next thing you should do?  Just pop your thumb drive onto
	your system and read the <filename>messages</filename> log. When
	you see "USB device found," then Bob's your uncle.
      </para>
    </example>
    <example>
      <title>Correct style</title>
	
	<!-- I prefer "correct." See above. [PWF] -->
	
      <para>
        After you complete the configuration changes above, attach the
	USB removable media to your system.  Use the
	<command>dmesg</command> command to examine the kernel message
	log.  The message <computeroutput>USB device
	  found</computeroutput> indicates that your device was
	installed successfully.
      </para>
    </example>
    <para>
      The first example is more conversational English, which is not
      appropriate for official written documentation.  The second
      example is more formal, but as a result it is easier to
      comprehend, both for native readers and translators.
    </para>
    <para>
      Following style rules and guidelines also makes readers more
      comfortable with a set of documents.  Consistent style enhances
      the professional appearance of documentation, and its perceived
      value. On the other hand, lapses in punctuation or poor grammar
      negatively affect a reader's reaction to written material.  A
      reader can feel that an otherwise correct technical document is
      lacking in authority, simply because it is poorly written. Readers
      feel at ease when they do not have to struggle to understand an
      author's use of language.
    </para>
    <para>
      This chapter cannot possibly cover enough material to make every
      reader a good writer.  Some manuals devoted entirely to writing
      style are themselves hundreds of pages long.  This chapter
      provides enough guidelines for intermediate writers to understand
      style usage in technical documentation.
    </para>
    <para>
      If you are not a practiced writer, whether of technical
      documentation or otherwise, you may benefit from other style
      resources.  The following list is far from comprehensive, but
      provides a starting point:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <citetitle>The Elements of Style</citetitle>, by William
	  Strunk.  Basic rules and links to online versions can be found
	  at: <ulink
	    url="http://en.wikipedia.org/wiki/The_Elements_of_Style">http://en.wikipedia.org/wiki/The_Elements_of_Style</ulink>
        </para>
      </listitem>
<!-- placeholder for when it's ready
        <para>
          <citetitle>The Elements of Style</citetitle>, by William
          Strunk.  Fedora Docs Project version: <ulink
            url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink>
        </para>
-->     
      <listitem>
        <para>
          <citetitle>The Chicago Manual of Style</citetitle>, by the
	  University of Chicago Press.  Online version: <ulink
	    url="http://www.chicagomanualofstyle.org/">http://www.chicagomanualofstyle.org/</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <citetitle>Paradigm Online Writing Assistant</citetitle>,
	  maintained by Chuck Guilford, Ph.D.  Online only: <ulink
	    url="http://www.powa.org/">http://www.powa.org/</ulink>
        </para>
      </listitem>
    </itemizedlist>
    <para>
      There are many free software documentation projects which have
      developed their own style guidelines.  This chapter, in fact,
      draws heavily on the <citetitle>GNOME Documentation Style
	Guidelines</citetitle> (<firstterm>GDSG</firstterm>).  You may
      read the original <citetitle>GDSG</citetitle> at <ulink
	url='http://developer.gnome.org/documents/style-guide/'>http://developer.gnome.org/documents/style-guide/</ulink>.
    </para>
     
  </section>
   
  <section id="sn-tech-docs-fundamentals">
   
    <title>Fundamental Concepts of Technical Documentation</title>
     
    <note>
      <title>Bibliographic Information</title>
      <para>
        This section is drawn primarily from the
	<citetitle>GDSG</citetitle>.
      </para>
    </note>
     
      <!-- This section will reproduce mostly what is in Chapter 1 of
      the GDSG.  There may be minor changes.  FIXME: Make sure the
      appropriate front matter of the Documentation Guide includes
      attribution as required by the GNU FDL. -->

    <para>
      This chapter provides a brief introduction to writing technical
      documentation.
    </para>

    <section id="sn-fundamentals-1">
      <title>General Style Requirements</title>
      <para>
        Technical writing for the &FP; imposes special constraints
	beyond the basic requirements of good prose.  Good &FED;
	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>Conforming</term> <!-- I'm having issues with the
          sketchy definition of this non-dictionary word and the
          associated text.  Not wrong, per se, just wishing for
          something better.  This note shall remind us! - kwade -->
	  <!-- Hopefully this change helps.  Makes sense according to the
          gdict tool in Core, at least.  - PWF -->
          <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 <citetitle>The Elements of Style</citetitle> (<ulink
		url="http://en.wikipedia.org/wiki/The_Elements_of_Style">http://en.wikipedia.org/wiki/The_Elements_of_Style</ulink>) 
	      to help make your writing clear.
            </para>
<!-- placeholder for when this is published:
            <para>
              Read <citetitle>The Elements of Style</citetitle>
                &FED;-version (<ulink
                url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</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.  Refer to <xref
                linkend="sn-fundamentals-2"/> for specific guidelines.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section id="sn-fundamentals-2">
      <title>Golden Rules</title>
      <para>
        This section contains some basic style guidelines.  Subsequent
	sections in this chapter expand on these guidelines to give more
	detailed guidance.
      </para>
      <variablelist>
        <varlistentry>
          <term>Golden Rule 1: Be brief</term>
          <listitem>
            <itemizedlist>
              <listitem>
                <para>
                  Limit each sentence to fewer than 25 words.
                </para>
              </listitem>
              <listitem>
                <para>
                  Limit each procedure step to 23 words.
                </para>
              </listitem>
            </itemizedlist>
            <example id="ex-golden-rule-1-wrong">
              <title>Incorrect: Too long</title>
              <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>
            </example>
            <example id="ex-golden-rule-1-right">
              <title>Correct: Less wordy</title>
              <para>
                Normally, the kernel stores the data in memory prior to
		periodically writing the data to the disk.
              </para>
            </example>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Golden Rule 2: Be organized</term>
          <listitem>
            <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>
            <example id="ex-golden-rule-2-wrong">
              <title>Incorrect: Disorganized topics</title>
              <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>
            </example>
            <example id="ex-golden-rule-2-right">
              <title>Correct: Organized topics</title>
              <para>
                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>
            </example>
            <tip>
              <para>
                Plan the order of paragraphs before you start writing.
		Decide which topic you want to cover in each paragraph.
              </para>
            </tip>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Golden Rule 3: Be demonstrative</term>
          <listitem>
            <para>
              Use explicit examples to demonstrate how an application
	      works.  Provide instructions rather than descriptions.
            </para>
            <example id="ex-golden-rule-3-wrong">
              <title>Incorrect: Describes but does not
		demonstrate</title>
              <para>
                There is a text box that you can use to find out the
		definition of a word.
              </para>
            </example>
            <example id="ex-golden-rule-3-right">
              <title>Correct: Demonstrates usage</title>
              <para>
                To request a definition of a word, type the word in the
		text box, then select <guilabel>Lookup</guilabel>.
              </para>
            </example>
            <tip>
              <para>
                Do not apply this guideline too rigidly.  Sometimes you
		must explain how software works to support your how-to
		examples.
              </para>
            </tip>
          </listitem>
        </varlistentry>
        <varlistentry id="vle-golden-rule-4">
          <term>Golden Rule 4: Be objective</term>
          <listitem>
            <para>
              Write in a neutral tone.
            </para>
            <example id="ex-golden-rule-4-wrong">
              <title>Incorrect: Sentence takes sides</title>
              <para>
                The applet is a handy little screen grabber.
              </para>
            </example>
            <example id="ex-golden-rule-4-right">
              <title>Correct: Sentence is objective</title>
              <para>
                Use the applet to take screenshots.
              </para>
            </example>
          </listitem>
        </varlistentry>
      </variablelist>

    </section>

    <section id="sn-fundamentals-3">

      <title>Tone</title>
      <para>
        Inappropriate tone hinders reader access to information.  A
	neutral tone free of opinion or personal flavor improves the
	reader's comprehension.  Neutral tone helps writers to work in
	parallel on a large technical documentation project.
	Furthermore, additional writers may join the project at any
	time.  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:
      </para>
      <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>
    </section>
    <section id="sn-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.  Consider 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>
    </section>
    <section id="sn-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>
    </section>
    <section id="sn-fundamentals-7">
      <title>New Users</title>
      <para>
        New users to &FC; are likely to consult online tutorials for
	guidance about unfamiliar applications or functionality.  Each
	tutorial should contain enough introductory information to tell
	new users how to start using the relevant functions.  Each
	tutorial should also contain enough usage instructions to tell
	users the different actions that they can perform with the
	command or function.  Keep these instructions task-oriented. Do
	not describe GUI screens, dialogs, and dialog elements in a
	tutorial, unless there is an unusual feature that affects your
	instructions.
      </para>
    </section>
    <section id="sn-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>
    </section>
    <section id="sn-fundamentals-9">
      <title>Do Not Offend Your Audience</title>
      <para>
        To avoid offending your readers, apply the following guidelines
	to your documentation:
      </para>
      <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 <literal>documentation</literal>
	      instead of the term <literal>docs</literal>.  A term may
	      be jargon if it fails all the following conditions:
            </para>
            <itemizedlist>
              <listitem>
                <para>
                  The term does not appear in the <citetitle>&FED;
		    Jargon Buster</citetitle> (<ulink
		    url="http://fedora.redhat.com/docs/jargon-buster/">http://fedora.redhat.com/docs/jargon-buster/</ulink>).
                </para>
              </listitem>
              <listitem>
                <para>
                  The term does not appear in the <citetitle>American
		    Heritage Dictionary</citetitle> (<ulink
		    url="http://www.bartleby.com/61/">http://www.bartleby.com/61/ 
		  </ulink>).
                </para>
              </listitem>
              <listitem>
                <para>
                  The term does not appear in the glossary of the manual
		  that you are writing.
                </para>
              </listitem>
              <listitem>
                <para>
                  The term is not defined in the body text of the manual
		  that you are writing.
                </para>
              </listitem>
            </itemizedlist>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Avoid gender-specific language</term>
          <listitem>
            <para>
              Pronoun constructions such as <literal>his/her</literal>
	      or <literal>s/he</literal> 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>
        Other parts of this guide discuss in more detail tone and
	language usage that can cause offense.
      </para>

    </section>

  </section>

  <section id="sn-grammar-and-usage">

    <title>Grammar and Usage Guidelines</title>

    <note>
      <title>Bibliographical Information</title>
      <para>
        This section is drawn partly from the
	<citetitle>GDSG</citetitle>, and partly from <citetitle>The
	  Elements of Style</citetitle>, updated as necessary for the
	needs of 21st-century technical documentation writers.
      </para>
    </note>

      <!-- FIXME: Again, check attribution viz.  GNU FDL.  This will be more work
      than the previous section. -->

    <para>
      This section contains an alphabetical list of grammar and usage
      guidelines for use in &FED; documentation.  Many of these
      guidelines are only applicable to English-language usage, refer to
      the <citetitle>American Heritage Dictionary</citetitle> (<ulink
	url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) 
      and the <citetitle>Chicago Manual of Style</citetitle> (<ulink
	url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.)
    </para>
    <variablelist>
      <varlistentry>
        <term>Abbreviations</term>
        <listitem>
          <para>
            A shortened form of a word or phrase that takes the place of
	    the full word or phrase, such as <literal>Dr.</literal>,
	    <literal>a.m.</literal>, <literal>p.m.</literal>, and so on.
	    Apply the following rules when you use abbreviations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Avoid creating new abbreviations.  Unfamiliar
		abbreviations can confuse rather than clarify a concept.
              </para>
            </listitem>
            <listitem>
              <para>
                Do not explain or expand familiar abbreviations.
              </para>
            </listitem>
            <listitem>
              <para>
                Do not include familiar abbreviations in the glossary of
		your manual.
              </para>
            </listitem>
          </itemizedlist>
          <para>
            For abbreviations of phrases, such as
	    <literal>i.e.</literal> for "in other words" and
	    <literal>e.g.</literal> for "for example", do not use the
	    abbreviation.  Spell out the entire phrase.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Adjectives</term>
        <listitem>
          <para>
            Use adjectives with caution.  If an adjective is necessary
	    to differentiate between items, then use adjectives.  In all
	    cases, test whether the phrase can stand alone without the
	    adjective.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Acronyms</term>
        <listitem>
          <para>
            A term that represents a multi-word term.  Typically,
	    acronyms are formed in the following ways:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                From the first letters of each word in a compound term,
		for example Table of Contents (TOC).
              </para>
            </listitem>
            <listitem>
              <para>
                From recognizable parts of a compound term, such as GNU
		Object Model Environment (GNOME).
              </para>
            </listitem>
          </itemizedlist>
          <para>
            Apply the following rules when you use acronyms:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                On the first occurrence of an acronym, spell out the
		full term, with the acronym in parentheses.
              </para>
            </listitem>
            <listitem>
              <para>
                Do not spell out the full compound for well-known
		acronyms, unless you think the information is useful for
		readers.
              </para>
            </listitem>
            <listitem>
              <para>
                Avoid creating new acronyms.  Unfamiliar acronyms can
		confuse rather than clarify a concept.
              </para>
            </listitem>
            <listitem>
              <para>
                Write the acronym in uppercase letters, unless there is
		a compelling case for lowercase.
              </para>
            </listitem>
            <listitem>
              <para>
                Include the acronym and the full term in the glossary of
		your manual.
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Adverbs</term>
        <listitem>
          <para>
            Use adverbs with caution.  If an adverb is necessary to
	    qualify the function of a component, then use an adverb.  In
	    all cases, test whether the phrase can stand alone without
	    the adverb.  Classic superfluous adverbs
	    <literal>simply</literal>, <literal>easily</literal>,
	    <literal>quickly</literal>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Anthropomorphism</term>
        <listitem>
          <itemizedlist>
            <listitem>
              <para>
                Do not apply emotions, desires, or opinions to software
		applications.
              </para>
            </listitem>
            <listitem>
              <para>
                Do not apply a sense of location or dimension to a
		software application.  A user can not be "in" a text
		editor.
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Articles</term>
        <listitem>
          <para>
            Do not use the definite article <literal>the</literal> to
	    begin any of the following items:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Manual titles
              </para>
            </listitem>
            <listitem>
              <para>
                Chapter titles
              </para>
            </listitem>
            <listitem>
              <para>
                Headings
              </para>
            </listitem>
            <listitem>
              <para>
                Figure captions
              </para>
            </listitem>
            <listitem>
              <para>
                Table captions
              </para>
            </listitem>
            <listitem>
              <para>
                Callouts
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Apostrophe</term>
        <listitem>
          <para>
            Do not use apostrophes except where absolutely required
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Do not use apostrophes to denote possession.
              </para>
            </listitem>
            <listitem>
              <para>
                Do not use apostrophes to denote contractions.
              </para>
            </listitem>
            <listitem>
              <para>
                Do not use apostrophes to denote plurals.
              </para>
            </listitem>
          </itemizedlist>
          <example id="ex-apostrophe-wrong">
            <title>Incorrect: Apostrophes</title>
            <itemizedlist>
              <listitem>
                <para>
                  the <guimenu>Main Menu's</guimenu>
		  <guimenuitem>Help</guimenuitem> option
                </para>
              </listitem>
              <listitem>
                <para>
                  don't use the default option
                </para>
              </listitem>
              <listitem>
                <para>
                  several SCSI disk's
                </para>
              </listitem>
            </itemizedlist>
          </example>
          <example id="ex-apostrophe-right">
            <title>Correct: No apostrophes</title>
            <itemizedlist>
              <listitem>
                <para>
                  the <guimenuitem>Help</guimenuitem> option on the
		  <guimenu>Main Menu</guimenu>
                </para>
              </listitem>
              <listitem>
                <para>
                  do not use the default option
                </para>
              </listitem>
              <listitem>
                <para>
                  several SCSI disks
                </para>
              </listitem>
            </itemizedlist>
          </example>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Brackets</term>
        <listitem>
          <itemizedlist>
            <listitem>
              <para>
                Do not use brackets [such as these] as a substitute for
		parentheses (such as these).
              </para>
            </listitem>
            <listitem>
              <para>
                Use brackets for optional command line entries.
              </para>
            </listitem>
            <listitem>
              <para>
                Do not use angle brackets to indicate variables in text,
		instead use the <sgmltag
		  class="starttag">replaceable</sgmltag> tag. Refer to
		<xref linkend="sn-xml-tags-replaceable"/> for
		information about using this tag.
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Capitalization</term>
        <listitem>
          <para>
            Capitalize in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                All letters in acronyms, unless the acronym is a
		well-known exception
              </para>
            </listitem>
            <listitem>
              <para>
                Initial letter of the first word in a list
              </para>
            </listitem>
            <listitem>
              <para>
                Initial letter of the first word in a callout
              </para>
            </listitem>
            <listitem>
              <para>
                Initial letter of a key name, such as the
		<keycap>Shift</keycap> key
              </para>
            </listitem>
            <listitem>
              <para>
                Initial letter of a sentence
	      </para>
	      <note>
		<title>Command Names</title>
		<para>
		  Avoid starting a sentence with a command name or
		  application name that has a lowercase initial letter.
		</para>
	      </note>
            </listitem>
            <listitem>
              <para>
                Initial letter of a complete sentence after a colon
              </para>
            </listitem>
          </itemizedlist>
          <para>
            Do not capitalize in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                A compound term that is followed by an abbreviation or
		an acronym
              </para>
            </listitem>
            <listitem>
              <para>
                When you want to emphasize something
              </para>
            </listitem>
            <listitem>
              <para>
                Variable names
              </para>
            </listitem>
            <listitem>
              <para>
                The initial letter of an incomplete sentence after a
		colon
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Captions</term>
        <listitem>
          <para>
            Use the same rules as for headings, for all captions
	    accompanying figures and tables.  Do not put a period at the
	    end of a caption.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Colon</term>
        <listitem>
          <para>
            Use a colon in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                To introduce a list
              </para>
            </listitem>
            <listitem>
              <para>
                Before an explanation
              </para>
            </listitem>
            <listitem>
              <para>
                After an introduction
              </para>
            </listitem>
          </itemizedlist>
          <para>
            Do not use a colon in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                To introduce a figure or a table
              </para>
            </listitem>
            <listitem>
              <para>
                To introduce headings
              </para>
            </listitem>
            <listitem>
              <para>
                At the end of an introduction to a procedure
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Column headings</term>
        <listitem>
          <para>
            Use the same rules as for headings.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Comma</term>
        <listitem>
          <para>
            Use commas in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                To separate items in a series
              </para>
            </listitem>
            <listitem>
              <para>
                To separate the parts of a sentence
              </para>
            </listitem>
            <listitem>
              <para>
                To separate nonrestrictive phrases
              </para>
            </listitem>
            <listitem>
              <para>
                Instead of dashes to set off appositives
              </para>
            </listitem>
            <listitem>
              <para>
                With <emphasis>for example</emphasis> and similar
		expressions
              </para>
            </listitem>
          </itemizedlist>
          <para>
            Do not use commas in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                In a series of adjectives used as one modifier
              </para>
            </listitem>
            <listitem>
              <para>
                Between two short independent clauses
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Commands</term>
        <listitem>
          <para>
            Do not use commands as verbs.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry id="vle-contractions">
        <term>Contractions</term>
        <listitem>
          <para>
            Do not use contractions such as <emphasis>can't</emphasis>,
	    <emphasis>don't</emphasis>, or <emphasis>isn't</emphasis>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Dash</term>
        <listitem>
          <para>
            Do not use the em dash or the en dash.  Use a paragraph
	    break or a colon instead, where you want to create an
	    introductory piece of text.  If you have several items that
	    you want to introduce, then you can use a variable list.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Ellipsis</term>
        <listitem>
          <para>
            Use an ellipsis in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                To show that you have omitted something from a sentence
              </para>
            </listitem>
            <listitem>
              <para>
                To indicate a pause when you quote displayed text
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Fractions</term>
        <listitem>
          <para>
            Follow these rules when using fractions:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Use numerals for fractions in tables and in units of
		measurement, but spell out fractions in prose.
              </para>
            </listitem>
            <listitem>
              <para>
                Use a space between a numeral and a related fraction, if
		there is a possible ambiguity.  For example: 1 1/2
		instead of 11/2.
              </para>
            </listitem>
            <listitem>
              <para>
                If a fraction is used in a compound modifier, insert a
		hyphen between the fraction and the unit of measurement.
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Gender</term>
        <listitem>
          <para>
            Refer to <xref linkend="sn-fundamentals-9"/>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Grammar</term>
        <listitem>
          <para>
            Use standard American English grammar rules, refer to the
	    <citetitle>Chicago Manual of Style</citetitle> (<ulink
	      url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> 
	      http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.)
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Headings</term>
        <listitem>
          <para>
            Use the following capitalization rules in headings:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Initial uppercase letter of the first word
              </para>
            </listitem>
            <listitem>
              <para>
                Initial uppercase letter for all nouns, adjectives, and
		verbs.
              </para>
            </listitem>
            <listitem>
              <para>
                All lowercase letters for conjunctions, articles, and
		prepositions of fewer than four letters
              </para>
            </listitem>
            <listitem>
              <para>
                Initial uppercase letter for prepositions of four
		letters or longer
              </para>
            </listitem>
            <listitem>
              <para>
                Initial uppercase letter for conjunctions of four
		letters or longer
              </para>
            </listitem>
          </itemizedlist>
	    <!-- <para> See <xref linkend="infodesign-2"/> for more
	    information about headings. </para> -->
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Hyphen</term>
        <listitem>
          <para>
            Use hyphens in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para> With a numeral in a compound modifier
              </para>
            </listitem>
            <listitem>
              <para>
                To prevent ambiguity
              </para>
            </listitem>
            <listitem>
              <para>
                With some standard prefixes and suffixes.  Use the
		<citetitle>American Heritage Dictionary</citetitle>
		(<ulink
		  url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) 
		for guidance
              </para>
            </listitem>
            <listitem>
              <para>
                In spelled-out fractions
              </para>
            </listitem>
            <listitem>
              <para>
                In variable names of two or more words, such as
		<replaceable>directory-name</replaceable>.  Note:
		<replaceable>filename</replaceable> is an exception.
              </para>
            </listitem>
          </itemizedlist>
          <para>
            Do not use hyphens in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                For industry-accepted terms
              </para>
            </listitem>
            <listitem>
              <para>
                To construct verbs
              </para>
            </listitem>
            <listitem>
              <para>
                With an adverb ending in <emphasis>ly</emphasis>
              </para>
            </listitem>
            <listitem>
              <para>
                With numerals as single modifiers
              </para>
            </listitem>
            <listitem>
              <para>
                With a word that is listed as unhyphenated in the
		<citetitle>American Heritage Dictionary</citetitle>
		(<ulink
		  url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>), 
		and that uses a common prefix
              </para>
            </listitem>
            <listitem>
              <para>
                With trademarked terms
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Latin terms</term>
        <listitem>
          <para>
            Do not use Latin terms.  Use an equivalent English term
	    instead.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Like</term>
        <listitem>
          <para>
            Do not use the term <emphasis>like</emphasis> to denote
	    equivalence or similarity.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Lists</term>
        <listitem>
          <para>
            Introduce a list with a complete sentence that ends with a
	    colon.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Numbers</term>
        <listitem>
          <para>
            Spell out numbers in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para> Numbers from zero through nine unless the number is
		part of a measurement
              </para>
            </listitem>
            <listitem>
              <para>
                Approximations
              </para>
            </listitem>
            <listitem>
              <para>
                Extreme values such as <emphasis>million</emphasis>, but
		precede the value with a numeral
              </para>
            </listitem>
            <listitem>
              <para>
                Any number that begins a sentence
              </para>
            </listitem>
            <listitem>
              <para>
                A number that is immediately followed by a numeral, for
		example: <literal>two 10 MB files</literal>
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Numerals</term>
        <listitem>
          <para>
            Use numerals in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                The number 10 or greater
              </para>
            </listitem>
            <listitem>
              <para> Negative numbers
              </para>
            </listitem>
            <listitem>
              <para>
                Most fractions
              </para>
            </listitem>
            <listitem>
              <para>
                Percentages
              </para>
            </listitem>
            <listitem>
              <para>
                Decimals
              </para>
            </listitem>
            <listitem>
              <para>
                Measurements
              </para>
            </listitem>
            <listitem>
              <para>
                Units of time smaller than one second
              </para>
            </listitem>
            <listitem>
              <para>
                References to bits and bytes
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Parentheses</term>
        <listitem>
          <para>
            Use parentheses in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                To contain the abbreviation of a term on the first
		occurrence of the full term
              </para>
            </listitem>
            <listitem>
              <para>
		In man page references, specifically the section number
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Period</term>
        <listitem>
          <para>
            Use a period in the following situations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                To end a sentence
              </para>
            </listitem>
            <listitem>
              <para>
                In file and directory names
              </para>
            </listitem>
            <listitem>
              <para>
                In abbreviations that can be mistaken for words, such as
		a.m. and U.S.
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Punctuation</term>
        <listitem>
          <para>
            Use standard American English punctuation rules.  In
	    addition to the specific points of punctuation in this
	    section, refer also to the <citetitle>Chicago Manual of
	      Style</citetitle> (<ulink
	      url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.)
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Punctuation in numbers</term>
        <listitem>
          <para>
            Do not use a comma in numerals of four digits.  Use a comma
	    in numerals of more than four digits.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Quotation marks</term>
        <listitem>
          <para>
            Use quotation marks to indicate material that is taken
	    verbatim from another source.  Do not use quotation marks to
	    excuse terms from legitimacy.  If the term is not
	    legitimate, then use another term.  If you must use that
	    term, declare the term in the glossary and make the term
	    legitimate.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>See v.  Refer to</term>
        <listitem>
          <para>
            When referring a user to another resource, use "refer to"
	    instead of "see", and "refer also to" instead of "see also".
	    This differentiates from the <sgmltag
	      class="starttag">see</sgmltag> and <sgmltag
	      class="starttag">seealso</sgmltag> tags that are used in
	    indexing.  These tags create special links in the index.  To
	    be consistent throughout the document, we reserve the
	    special words "see" and "see also" for hyperlinked index
	    references, and use "refer to" and "refer also to" for
	    non-hyperlinked and non-indexed references.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Semicolon</term>
        <listitem>
          <para>
            Do not use semicolons.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Slash</term>
        <listitem>
          <para>
            Except where required as part of a filename, do not use
	    slashes "/" in your writing.  The construction
	    <literal>and/or</literal>, for example, does not exist. Use
	    one or the other term instead.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Spelling</term>
        <listitem>
          <para>
            Use standard American English spelling rules, refer to the
	    <citetitle>American Heritage Dictionary</citetitle> (<ulink
	      url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) 
	    for guidelines.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Titles</term>
        <listitem>
          <para>
            For manual titles use the same rules as for headings.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Units</term>
        <listitem>
          <para>
            Follow these rules when using units:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Use standard abbreviations for units of measurements, do
		not invent your own abbreviations.
              </para>
            </listitem>
            <listitem>
              <para>
		<!-- See <xref linkend="units"/> for a list of units
		relevant to the GNOME Desktop. --> For further
		guidelines, refer to the <citetitle>IEEE Standard
		  Dictionary of Electrical and Electronics
		  Terms</citetitle>.
              </para>
            </listitem>
            <listitem>
              <para>
                Use periods for abbreviated units that might be mistaken
		for a word.
              </para>
            </listitem>
            <listitem>
              <para>
                Most standard abbreviations of units account for both
		singular and plural usage.
              </para>
            </listitem>
            <listitem>
              <para>
                Insert a space between the numeral and the unit of
		measurement.
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
    </variablelist>

  </section>

  <section id="sn-composition-tips">

    <title>Composition Tips</title>

<!--

    This section will collect miscellanea and advice for specific
    situations that the FDP editors encounter.  I hope they will feel
    free to e-mail me sticky situations or particularly interesting
    examples of work they've beautified.  Hopefully not too much will be
    drawn from my own work! - PWF.

-->

    <para>
      This section contains usage tips based on situations the &FDP;
      editors have encountered in the past.  You should read and
      understand these examples to improve your own documentation.  The
      &FDP; editors welcome additional examples.
    </para>

    <section id="sn-misc-active-voice">
      <title>Active Voice</title>
      <para>
        Always use active voice, except when it is awkward to do so. The
	tutorial tells the user how to accomplish a task, and should
	give instructions clearly and concisely.  Avoid using "must,"
	"need to," and the like.  These words are redundant in a
	tutorial, since the reader assumes you are outlining necessary
	steps to accomplish a task.  Also avoid using "maybe," "might,"
	and other words that indicate you are unsure about the subject
	matter.  Your tutorial should cover a subject authoritatively.
	The reader should never be concerned about unknown effects of
	following the tutorial.
      </para>
      <example id="ex-misc-passive-voice">
        <title>Incorrect: Passive voice</title>
        <para>
          The <command>yum update</command> command must be run.
        </para>
        <para>
          You might want to run the <command>yum update</command>
	  command.
        </para>
      </example>
      <example id="ex-misc-active-voice">
        <title>Correct: Active voice</title>
        <para>
          Run the <command>yum update</command> command.
        </para>
      </example>
    </section>

    <section id="sn-present-tense">
      <title>Present Tense</title>
      <para>
	Write in the present tense.  A good rule of thumb is that the
	words "will" and "shall" are almost never needed in describing
	what the user should do or see.  They add unnecessary length to
	sentences and can confuse translators.  They are also often
	indicators of passive voice; refer also to <xref
	  linkend="sn-misc-active-voice"/>.
      </para>
      <example id="ex-misc-future-tense">
        <title>Incorrect: Future tense</title>
        <para>
          The application will display a list of target files.
        </para>
        <para>
          A list of target files will be displayed by the application.
        </para>
      </example>
      <example id="ex-misc-present-tense">
        <title>Correct: Present tense</title>
        <para>
          The application displays a list of target files.
        </para>
      </example>
    </section>
	 
    <section id="sn-narrative-voice">
      <title>Narrative Voice</title>
      <para>
        Do not use the first person "I," "we," or "us" to refer to
	yourself the writer (whether including the reader or not), the
	&FDP;, the &FED; community, or any other group.  Do not refer to
	users with a third person pronoun ("he," "she," or "he or she")
	or the word "one." It is acceptable to refer to the reader with
	the second person pronoun "you."
      </para>
      <example id="ex-misc-wrong-person">
        <title>Incorrect: First or third person</title>
        <para>
          As described in the last section, I always run
	  <command>up2date</command> before configuring the Samba
	  server.
        </para>
        <para>
          If the user needs to back up his or her files, s/he should use
	  the <command>tar</command> or <command>cpio</command> command.
        </para>
      </example>
      <example id="ex-misc-correct-person">
        <title>Correct: Second (or no) person</title>
        <para>
          Refer to the section on <command>up2date</command> before
	  configuring the Samba server.
        </para>
        <para>
          If necessary, users can back up files with the
	  <command>tar</command> or <command>cpio</command> command.
        </para>
      </example>
    </section>

    <section id="sn-misc-negative">
      <title>Negative Words</title>
      <para>
	Avoid negative words when possible, since they give
	documentation an overly dogmatic tone.  The word "avoid" is
	useful for this purpose.  Note that contractions are often used
	for negative words such as <emphasis>don't</emphasis> or
	<emphasis>can't</emphasis>.  Refer to <xref
	  linkend="vle-contractions" />.
      </para>
    </section>

    <section id="sn-misc-uncertainty">
      <title>Uncertainty</title>
      <para>
        Avoid overuse of "typically," "usually," "most of," "many," and
	the like.  While occasional use of these constructions is
	acceptable, overuse reduces the authority of your documentation.
	The documentation should adequately cover a stock installation
	of &FC;.  It is impossible for a tutorial-length document to
	cover every possible configuration scenario.  Address the most
	common scenarios and note discrepancies only as required.
      </para>
    </section>
	
    <section id="sn-misc-offtopic">
      <title>Redundant Coverage</title>
      <para>
        Avoid covering redundant material, such as how to update a &FC;
	system.  These overarching topics may be covered in other
	tutorials.  Writers frequently violate this guideline because
	they feel their tutorial is not long enough.  Keep your tutorial
	from wandering off-topic.  Instead, refer the reader to a
	separate tutorial whenever possible for complete coverage of
	that topic.
      </para>
    </section>

    <section id="sn-misc-importance">
      <title>Self-referential Value Judgments</title>
      <para>
	Avoid statements such as "One of the most important things to do
	is <replaceable>XYZ</replaceable>." If the procedure is
	important, the reader already expects it to be in your tutorial.
	The converse is also true:  If a procedure appears in your
	tutorial, the reader expects it is important.  This is
	especially true if you use a whole section for the procedure in
	question.  Merely state, "Do <replaceable>XYZ</replaceable>."
	Then elaborate as required.  If the whole section concerns how
	to do <replaceable>XYZ</replaceable>, leave this sentence out
	entirely.  Refer also to <xref linkend="vle-golden-rule-4" />.
      </para>
    </section>

    <section id="sn-misc-precision">
      <title>Precision of Language</title>
      <para>
        Use precise words for actions users should take.  Do not
	instruct users to "go" to a selection, or "find" a menu.
      </para>
      <example id="ex-precision-wrong">
        <title>Incorrect: Imprecise wording</title>
        <itemizedlist>
          <listitem>
            <para>
              Go to the <guimenu>Main Menu</guimenu> ->
	      <guimenuitem>Foobar</guimenuitem>
            </para>
          </listitem>
          <listitem>
            <para>
              Find the option labeled <guilabel>Search</guilabel>
            </para>
          </listitem>
        </itemizedlist>
      </example>
      <example id="ex-precision-right">
        <title>Correct: Precise wording</title>
        <itemizedlist>
          <listitem>
            <para>
              From the <guimenu>Main Menu</guimenu>, select
	      <guimenuitem>Foobar</guimenuitem>
            </para>
          </listitem>
          <listitem>
            <para>
              Select the <guilabel>Search</guilabel> option
            </para>
          </listitem>
        </itemizedlist>
      </example>
      <important>
        <title>Do Not Discriminate Against Non-GUI Users</title>
        <para>
          If you are writing about a GUI-only application, you may use
	  "click" freely.  If you are writing about an application that
	  has a text-mode interface, use "select" instead as shown
	  above.
        </para>
      </important>

    </section>
	   
    <section id="sn-misc-docbook-tips">
      <title>DocBook Tips</title>
      <para>
        This section contains tips on how to use DocBook tags more
	effectively in your documentation.
      </para>

      <section id="sn-misc-admonitions">
        <title>Admonitions</title>
        <para>
          Avoid overuse of admonitions.  Keep admonitions short and
	  effective by using only the most important material inside the
	  admonition.  Move any background material required to explain
	  the admonition statements outside the admonition.  Use a short
	  but descriptive title for an admonition.  Use title case for
	  the admonition title.
        </para>
        <example id="ex-misc-ineffective-admonition">
          <title>Incorrect: Lengthy admonition</title>
          <para>
	      <warning>
              <title>Use <command>sfdisk</command> to check input</title>
              <para>
                The <command>sfdisk</command> command accepts a script
		file as standard input to set up partitions on a hard
		disk.  Sometimes <command>sfdisk</command> will simply
		reject an erroneous input file.  In other cases, it will
		use the input verbatim, writing an incorrect partition
		table to your disk.  Always use the <command>sfdisk
		  -n</command> command to check your input file before
		writing to the disk.
              </para>
	      </warning>
          </para>
        </example>
        <example id="ex-misc-good-admonition">
          <title>Correct: Brief admonition</title>
          <para>
	    The <command>sfdisk</command> command accepts a script
	    file as standard input to set up partitions on a hard disk.
	    Sometimes <command>sfdisk</command> will simply reject an
	    erroneous input file.  In other cases, it will use the input
	    verbatim, writing an incorrect partition table to your disk.
	    <warning>
              <title>Check Input</title>
              <para>
                Always use the <command>sfdisk -n</command> command to
		check your input file before writing to the disk.
              </para>
	    </warning>
          </para>
        </example>
        <para>
          Avoid punctuation in titles for sections or admonitions,
	  except for commas only where demanded.  Use a title that says
	  something about the admonition comment, such as "Reboot
	  Required," instead of simply using the admonition type for a
	  title ("Note").
        </para>
	<para>
	  Follow the capitalization rules for headings in the title of
	  an admonition.
	</para>
      </section>

      <section id="sn-misc-replaceable">
        <title>The <sgmltag class="starttag">replaceable</sgmltag>
	  Tag</title>
        <para>
          If your documentation formally states a specific value will be
	  used as a convention, do not use the <sgmltag
	    class="starttag">replaceable</sgmltag> tag in your text or
	  examples.
        </para>
      </section>

      <section id="sn-misc-entities">
        <title>XML Entities</title>
        <para>
	  Use the entities provided by the &FDP;.  These entities are
	  found in the <filename>common/</filename> folder in the
	  <filename>fedora-docs</filename> distribution. (Refer also to
	  <xref linkend="ch-getting-files"/>.) For instance, do not use
	  abbreviations such as "FC2."  Instead, use the predefined
	  entities "&amp;FC; &amp;FCVER;," which produces the text "&FC;
	  &FCVER;."
        </para>
      </section>

    </section>
   
  </section>
 
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: xml
fill-column: 72
End:
-->