[documentation-guide] Updated the introduction, and began the section on the organization of the guide

[Jared Smith]

commit 6eb74fc67ab4ef79915b68a208ac78d8cb2e84ef
Author: Jared K. Smith <jaredsmith at jaredsmith.net>
Date:   Sun Mar 23 12:56:21 2014 -0400

    Updated the introduction, and began the section on the organization of the guide

 en-US/introduction.xml |   79 ++++++++++++++++++++++++++++++++---------------
 1 files changed, 54 insertions(+), 25 deletions(-)
---
diff --git a/en-US/introduction.xml b/en-US/introduction.xml
index 4ad0ca3..786e671 100644
--- a/en-US/introduction.xml
+++ b/en-US/introduction.xml
@@ -5,54 +5,83 @@
 ]>
 <chapter id="chap-documentation_guide-intro">
   <title>Introduction</title>
-  <para>This chapter will introduce you to some of the best
-practices that the Fedora Documentation Project uses to help its writers
-be most productive.  </para>
   <section>
     <title>Purpose of This Guide</title>
-    <para/>
+    <para>The purpose of this guide is to help you be successful as a
+writer, and to gain a better understanding of the tools and techniques
+that the Fedora Documentation team use.  We hope you'll dive right
+in and use this information to your advantage, and that it will also
+inspire you to join in our efforts to improve Fedora documentation.</para>
+    <para>This introductory chapter will introduce you to some of the best
+practices that the Fedora Documentation Project uses to help its writers
+be most productive.  In subsequent chapters, we'll walk you through a
+tutorial designed to teach you the tools and workflow we use.  Later in
+the book, we'll cover more advanced topics, such as publishing and translation.  
+Near the end of the book, we also include a style guide, which is intended to
+help bring a higher level of consistency and professionalism to all of the
+Fedora documentation.</para>
   </section>
   <section>
     <title>Tips for Success</title>
-      <para>Before we dive into the mechanics of the
+      <para>Before we dive into the mechanics of writing and publishing
 documentation, let's look at some important points that will help ensure
 your success in your documentation efforts.</para>
-    <section>
-      <title>Be Bold!</title>
-      <para>Although it might seem a bit trite at first
+    <variablelist>
+      <varlistentry>
+        <term>Be Bold!</term>
+        <listitem><para>Although it might seem a bit trite at first
   glance, the most important part of writing documentation is writing.
   There's no need to ask permission before writing... just start
-  writing!</para>
-    </section>
-    <section>
-      <title>Don't Let the Tools Scare You</title>
-      <para>The Fedora documentation group uses a number of
+  writing!  We also use technology to keep track of all the changes
+  that happen in our guides, so don't let your fear of ruining something
+  keep you from moving forward.  If you do somehow manage to mess things
+  up, we can always roll back to a previous version.</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>Don't Let the Tools Scare You</term>
+      <listitem><para>The Fedora documentation group uses a number of
   different tools, but please don't be intimidated by the tools.  A bit of
   practice and mentoring may be necessary to get proficient with the
   tools.  In the meantime, just write in a text editor of your choice, and
-  the text can always be converted into the proper format at a later time. </para>
+  the text can always be converted into the proper format at a later time,
+  either by you or by another member of the Fedora Documenation team.  Too
+  many times, we see people stop contributing when they feel uncomfortable
+  with the tools.  If the tools scare you, please keep writing and let other
+  members of the team deal with the tools.</para>
       <para>We will discuss the various tools in <xref
-  linkend="chap-documentation_guide-tools"/>.</para>
-    </section>
-    <section>
-      <title>There's a Team to Back You Up</title>
-      <para>Don't be afraid to ask for assistance.  The Fedora
+  linkend="chap-documentation_guide-tools"/>.</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>There's a Team to Back You Up</term>
+      <listitem><para>Don't be afraid to ask for assistance.  The Fedora
   documentation team is more than willing to help you both with writing
-  and with learning the tools and workflow.  If you're on IRC, join the
-  <literal>#fedora-docs</literal> channel on the Freenode network.
+  and with learning the tools and workflow.  If you're familiar with the
+  IRC chat system, please join the <literal>#fedora-docs</literal> channel
+  on the Freenode network.
     <indexterm significance="normal">
       <primary>IRC (Internet Relay Chat)</primary>
       <secondary>communicating with the Docs team</secondary>
     </indexterm>
-    We also have a mailing list where we discuss various issues related to
+  We also have a mailing list where we discuss various issues related to
   documentation.  For more information on the joining the mailing list,
   visit <ulink
   url="https://lists.fedoraproject.org/mailman/listinfo/docs"/>.</para>
-    </section>
+    <indexterm significance="normal">
+      <primary>mailing list</primary>
+      <secondary>communicating with the Docs team</secondary>
+    </indexterm>
+      </listitem>
+    </varlistentry>
+  </variablelist>
   </section>
   <section>
-    <title>Organization of This Guide</title>
-    <para/>
+    <title>Organization of this Guide</title>
+    <para>In <xref linkend="chap-community"/>, we will explain the Fedora
+  documentation community, and how you can join the volunteer effort to
+  make the world a better place, one instruction at a time.</para>
+    <para>In <xref linkend="chap-documentation_guide-workflow"/>, we explain the basic workflow
+  of writing documentation, formatting it, publishing it, and translating it.
+    </para>
   </section>
 </chapter>
 <!--