[documentation-guide: 1/2] Help flesh out the introduction

[Jared Smith]

commit b658d5d6751588db5e8a840871821d7f9857598d
Author: Jared K. Smith <jsmith at fedoraproject.org>
Date:   Sun Sep 11 11:09:29 2011 -0400

    Help flesh out the introduction

 en-US/introduction.xml |   66 ++++++++++++++++++++++++++++++++++++-----------
 en-US/tools.xml        |    2 +-
 2 files changed, 51 insertions(+), 17 deletions(-)
---
diff --git a/en-US/introduction.xml b/en-US/introduction.xml
index 53363a6..a49b9b8 100644
--- a/en-US/introduction.xml
+++ b/en-US/introduction.xml
@@ -4,22 +4,56 @@
 %BOOK_ENTITIES;
 ]>
 <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>Be bold!</title>
-		<para/>
-	</section>
-	<section>
-		<title>Don't let the tools scare you</title>
-		<para/>
-	</section>
-	<section>
-		<title>There's a team to back you up</title>
-		<para/>
-	</section>
+  <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/>
+  </section>
+  <section>
+    <title>Tips for success</title>
+      <para>Before we dive into the mechanics of the
+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
+  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
+  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>
+      <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
+  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.
+    <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
+  documentation.  For more information on the joining the mailing list,
+  visit <ulink
+  url="https://lists.fedoraproject.org/mailman/listinfo/docs"/>.</para>
+    </section>
+  </section>
+  <section>
+    <title>Organization of this guide</title>
+    <para/>
+  </section>
 </chapter>
 <!--
 Local variables:
diff --git a/en-US/tools.xml b/en-US/tools.xml
index 776abd3..adf348e 100644
--- a/en-US/tools.xml
+++ b/en-US/tools.xml
@@ -3,7 +3,7 @@
 <!ENTITY % BOOK_ENTITIES SYSTEM "documentation-guide.ent">
 %BOOK_ENTITIES;
 ]>
-<chapter id="chap-documentation_guide-Test_Chapter">
+<chapter id="chap-documentation_guide-tools">
 	<title>XML tools</title>
 	<para>
 		This chapter will walk you through a few of the commonly-used XML tools that will make it easier to work with DocBook files.