]> projects.mako.cc - fspm_howto/blobdiff - FreeSoftwareProjectManagementHOWTO.sgml
A diff fixing a ton of errors made by Andy King. The Diff follow
[fspm_howto] / FreeSoftwareProjectManagementHOWTO.sgml
index d85158d685b630b3e837b5f4fd936ca9b9f2c88e..902fa12544097a7d1de92a5b96563edd8352877f 100644 (file)
@@ -5,11 +5,11 @@
 <!-- Header -->
 
  <artheader>
 <!-- Header -->
 
  <artheader>
-  <title>Free Software Development HOWTO</title>
+  <title>Free Software Project Management HOWTO</title>
   
   <author>
    <firstname>Benjamin</firstname>
   
   <author>
    <firstname>Benjamin</firstname>
-   <othername>Mako</othername>
+   <othername>"Mako"</othername>
    <surname>Hill</surname>
    <affiliation>
     <address>
    <surname>Hill</surname>
    <affiliation>
     <address>
     </address>
    </affiliation>
   </author>
     </address>
    </affiliation>
   </author>
-  
+
   <revhistory>
   <revhistory>
+   <revision>
+    <revnumber>v0.3</revnumber>
+    <date>5 May 2001</date>
+    <authorinitials>bch</authorinitials>
+   </revision>
+
+   <revision>
+    <revnumber>v0.2.1</revnumber>
+    <date>10 April 2001</date>
+    <authorinitials>bch</authorinitials>
+   </revision>
+
    <revision>
     <revnumber>v0.2</revnumber>
     <date>8 April 2001</date>
    <revision>
     <revnumber>v0.2</revnumber>
     <date>8 April 2001</date>
     This HOWTO is designed for people with experience in programming
     and some skills in managing a software project but who are new to
     the world of free software. This document is meant to act as a
     This HOWTO is designed for people with experience in programming
     and some skills in managing a software project but who are new to
     the world of free software. This document is meant to act as a
-    guide to the non-technical aspects of free software development
-    and was written to be a crash course in the people skills that
-    aren't taught to commercial coders but that can make or break a
-    free software project.
+    guide to the non-technical aspects of free software project
+    management and was written to be a crash course in the people
+    skills that aren't taught to commercial coders but that can make
+    or break a free software project.
    </para>
   </abstract>
   
    </para>
   </abstract>
   
@@ -69,7 +81,7 @@
   </para>
 
   <para>
   </para>
 
   <para>
-   This HOWTO tries to do a lot of thing (probably too many), but it
+   This HOWTO tries to do a lot of things (probably too many), but it
    can't answer that question and won't attempt it. What this HOWTO
    will attempt to do is give your Free Software project a fighting
    chance--an edge. If you write a piece of crap that no one is
    can't answer that question and won't attempt it. What this HOWTO
    will attempt to do is give your Free Software project a fighting
    chance--an edge. If you write a piece of crap that no one is
     this is a new edition of this document, there may be errors and
     inaccuracies, that may of course be damaging to your system.
     Proceed with caution, and although this is highly unlikely, the
     this is a new edition of this document, there may be errors and
     inaccuracies, that may of course be damaging to your system.
     Proceed with caution, and although this is highly unlikely, the
-    author(s) do not take any responsibility for that.
+    author(s) does not take any responsibility for that.
    </para>
 
    <para>
    </para>
 
    <para>
    </para>
 
    <para>
    </para>
 
    <para>
-    You are strongly recommended to take a backup of your system 
+    You are strongly recommended to make a backup of your system 
     before major installation and backups at regular intervals.
    </para>
   </sect2>
     before major installation and backups at regular intervals.
    </para>
   </sect2>
   <sect2 id="newversions">
    <title>New Versions</title>
 
   <sect2 id="newversions">
    <title>New Versions</title>
 
-    <indexterm>
-     <primary>fswd!news on</primary>
-    </indexterm>
-
    <para>
    <para>
-    This is the second pre-release of this HOWTO. It is written to be
-    released to developers for critique and brainstorming and
-    submitted to Hampshire College for academic credit. Please keep in
-    mind that this version of the HOWTO is still in an infant stage
-    and will be revised extensively before it gets publicized widely.
+    This version is the part of the third pre-release cycle of this
+    HOWTO. It is written to be released to developers for critique and
+    brainstorming and submitted to Hampshire College for academic
+    credit. Please keep in mind that this version of the HOWTO is
+    still in an infant stage and will be revised extensively before it
+    gets publicized widely.
    </para>
 
    <para>
     The latest version number of this document should always be listed
    </para>
 
    <para>
     The latest version number of this document should always be listed
-    on <ulink url="http://people.debian.org/~mako/projects/howto">the projects
-    homepage </ulink> hosted by Debian.
+    on <ulink url="http://yukidoke.org/~mako/projects/howto">the projects
+    homepage </ulink> hosted by <ulink url="http://yukidoke.org">yukidoke.org.</ulink>
    </para>
 
    <para>
    </para>
 
    <para>
 
     <listitem>
      <para>
 
     <listitem>
      <para>
-      <ulink url="http://people.debian.org/~mako/projects/howto/FreeSoftwareDevelopment-HOWTO/t1.html">HTML</ulink>.
+      <ulink url="http://yukidoke.org/~mako/projects/howto/FreeSoftwareProjectManagement-HOWTO/t1.html">HTML</ulink>.
      </para>
     </listitem>
 
 
     <listitem>
      <para>
      </para>
     </listitem>
 
 
     <listitem>
      <para>
-      <ulink url="http://people.debian.org/~mako/projects/howto/FreeSoftwareDevelopment-HOWTO.html">HTML (single page)</ulink>.
+      <ulink url="http://yukidoke.org/~mako/projects/howto/FreeSoftwareProjectManagement-HOWTO.html">HTML (single page)</ulink>.
      </para>
     </listitem>
 
     <listitem>
      <para>
      </para>
     </listitem>
 
     <listitem>
      <para>
-       <ulink URL="http://people.debian.org/~mako/projects/howto/FreeSoftwareDevelopment-HOWTO.txt">plain text</ulink>.
+      <ulink URL="http://yukidoke.org/~mako/projects/howto/FreeSoftwareProjectManagement-HOWTO.txt">plain text</ulink>.
      </para>
     </listitem>
 
     <listitem>
      <para>
      </para>
     </listitem>
 
     <listitem>
      <para>
-      <ulink url="http://people.debian.org/~mako/projects/howto/FreeSoftwareDevelopment-HOWTO.ps.gz">Compressed postscript</ulink>.
+      <ulink url="http://yukidoke.org/~mako/projects/howto/FreeSoftwareProjectManagement-HOWTO.ps.gz">Compressed postscript</ulink>.
      </para>
     </listitem>
 
     <listitem>
      <para>
      </para>
     </listitem>
 
     <listitem>
      <para>
-      <ulink url="http://people.debian.org/~mako/projects/howto/FreeSoftwareDevelopment-HOWTO.sgml.gz">Compressed SGML source</ulink>.
+      <ulink url="http://yukidoke.org/~mako/projects/howto/FreeSoftwareProjectManagement-HOWTO.sgml.gz">Compressed SGML source</ulink>.
      </para>
     </listitem>
    </itemizedlist>
      </para>
     </listitem>
    </itemizedlist>
     In this version I have the pleasure of acknowledging:
    </para>
 
     In this version I have the pleasure of acknowledging:
    </para>
 
+   <para>
+    Anyone who gave me an idea for a better name and everyone who
+    assured me that a Project Management HOWTO didn't necessary imply
+    corporate.
+   </para>
+
+   <para>
+    Josh Crawford, Andy King, and Jaime Davila who all read through
+    this beast and gave me feedback that has helped me make changes
+    and improvements to this document. I can't thank you guys enough
+    for your help.
+   </para>
+
    <para>
     <emphasis>Karl Fogel</emphasis>, the author of <emphasis>Open
     Source Development with CVS</emphasis> published by the Coriolis
    <para>
     <emphasis>Karl Fogel</emphasis>, the author of <emphasis>Open
     Source Development with CVS</emphasis> published by the Coriolis
     url="http://www.debian.org">Debian Project</ulink>. The project
     has provided me with a home, a place to practice free software
     advocacy, a place to make a difference, a place to learn from
     url="http://www.debian.org">Debian Project</ulink>. The project
     has provided me with a home, a place to practice free software
     advocacy, a place to make a difference, a place to learn from
-    those how have been involved with the movement much longer than I,
+    those who have been involved with the movement much longer than I,
     and proof of a free software project that definitely, definitely
     works.
    </para>
     and proof of a free software project that definitely, definitely
     works.
    </para>
     <primary>fswd!starting</primary>
    </indexterm>
   <para>
     <primary>fswd!starting</primary>
    </indexterm>
   <para>
-   With very little argument, the beginning is the most difficult part
-   of successful free software development. Laying a firm foundation
-   will determine whether your project flourishes or withers away and
-   dies. It is also the subject that is of most immediate interest to
-   anyone reading this document as a tutorial.
+   With very little argument, the beginning is the most difficult
+   period in a project's life to do successful free software project
+   managment. Laying a firm foundation will determine whether your
+   project flourishes or withers away and dies. It is also the subject
+   that is of most immediate interest to anyone reading this document
+   as a tutorial.
   </para>
 
   <para>
    Starting a project involves a dilemma that you as a developer must
    try and deal with: no potential user for your program is interested
   </para>
 
   <para>
    Starting a project involves a dilemma that you as a developer must
    try and deal with: no potential user for your program is interested
-   in a program that doesn't work while the development process that
+   in a program that doesn't work, while the development process that
    you want to employ holds involvement of users as imperative.
   </para>
 
    you want to employ holds involvement of users as imperative.
   </para>
 
     <title>Identify and articulate your idea</title>
     <para>
      Eric S. Raymond writes about how free software projects start in
     <title>Identify and articulate your idea</title>
     <para>
      Eric S. Raymond writes about how free software projects start in
-     his essay, <quote>The Cathedral and the Bazaar,</quote> which
-     comes as required reading for any free software developer. It is
-     available <ulink
-     url="http://www.tuxedo.org/~esr/writings/cathedral-bazaar/">online
-     </ulink>.
+     his essay, <ulink
+     url="http://www.tuxedo.org/~esr/writings/cathedral-bazaar/"><quote>The
+     Cathedral and the Bazaar,</quote></ulink> which comes as required
+     reading for any free software developer. It is available online .
     </para>
 
     <para>
     </para>
 
     <para>
      In evaluating your idea, you need to first ask yourself a few
      questions.  This should happen before you move any further
      through this HOWTO. Ask yourself: <emphasis>Is the free software
      In evaluating your idea, you need to first ask yourself a few
      questions.  This should happen before you move any further
      through this HOWTO. Ask yourself: <emphasis>Is the free software
-     development model really is the right one for your
+     development model really the right one for your
      project?</emphasis>
     </para>
 
      project?</emphasis>
     </para>
 
     </para>
 
     <para>
     </para>
 
     <para>
-     Luckily, The Internet is a place so big and so diverse that,
+     Luckily, the Internet is a place so big and so diverse that,
      chances are, there is someone, somewhere, who shares your
      chances are, there is someone, somewhere, who shares your
-     interests and how feels the same <quote>itch.</quote> It is the
+     interests and who feels the same <quote>itch.</quote> It is the
      fact that there are so many people with so many similar needs and
      desires that introduces the third major question: <emphasis>Has
      somebody already had your idea or a reasonably similar
      fact that there are so many people with so many similar needs and
      desires that introduces the third major question: <emphasis>Has
      somebody already had your idea or a reasonably similar
       There are places you can go on the web to try and answer the
       question above. If you have experience with the free software
       community, you are probably already familiar with many of these
       There are places you can go on the web to try and answer the
       question above. If you have experience with the free software
       community, you are probably already familiar with many of these
-      sites. All of the resources listed bellow offer searching of
+      sites. All of the resources listed below offer searching of
       their databases:
      </para>
 
       their databases:
      </para>
 
         <term>Slashdot</term>
         <listitem>
         <para><ulink url="http://slashdot.org">Slashdot</ulink>
         <term>Slashdot</term>
         <listitem>
         <para><ulink url="http://slashdot.org">Slashdot</ulink>
-        provides <quote>News for Nerds: Stuff that Matters,</quote>
+        provides <quote>News for Nerds. Stuff that matters,</quote>
         which usually includes discussion of free software, open
         which usually includes discussion of free software, open
-        source, technology, and geek culture new and events. It is
-        not unusual for an particularly sexy development effort to be
-        announced here so it definitely worth checking.</para>
+        source, technology, and geek culture news and events. It is
+        not unusual for a particularly sexy development effort to be
+        announced here, so it is definitely worth checking.</para>
         </listitem>
        </varlistentry>
 
         </listitem>
        </varlistentry>
 
         <para><ulink url="http://sourceforge.net">SourceForge</ulink>
         houses and facilitates a growing number of open source and
         free software projects. It is also quickly becoming a nexus
         <para><ulink url="http://sourceforge.net">SourceForge</ulink>
         houses and facilitates a growing number of open source and
         free software projects. It is also quickly becoming a nexus
-        and an necessary stop for free software
+        and a necessary stop for free software
         developers. SourceForge's <ulink
         url="http://sourceforge.net/softwaremap/trove_list.php">software
         map</ulink> and <ulink url="http://sourceforge.net/new/"> new
         release</ulink> pages should be necessary stops before
         embarking on a new free software project. SourceForge also
         developers. SourceForge's <ulink
         url="http://sourceforge.net/softwaremap/trove_list.php">software
         map</ulink> and <ulink url="http://sourceforge.net/new/"> new
         release</ulink> pages should be necessary stops before
         embarking on a new free software project. SourceForge also
-        provides a at <ulink
+        provides a <ulink
         url="http://sourceforge.net/snippet/">Code Snippet
         Library</ulink> which contains useful reusable chunks of code
         in an array of languages which can come in useful in any
         url="http://sourceforge.net/snippet/">Code Snippet
         Library</ulink> which contains useful reusable chunks of code
         in an array of languages which can come in useful in any
         <listitem>
         <para><ulink url="http://www.google.com">Google</ulink> and
         <ulink url="http://www.google.com/linux"> Google's Linux
         <listitem>
         <para><ulink url="http://www.google.com">Google</ulink> and
         <ulink url="http://www.google.com/linux"> Google's Linux
-        Search</ulink>, provide powerful web searches that may reveal
+        Search</ulink>, provides powerful web searches that may reveal
         people working on similar projects. It is not a catalog of
         software or news like freshmeat or Slashdot, but it is worth
         checking to make sure you aren't pouring your effort into a
         people working on similar projects. It is not a catalog of
         software or news like freshmeat or Slashdot, but it is worth
         checking to make sure you aren't pouring your effort into a
 
      <para>
       For many developers this may be the single most difficult aspect
 
      <para>
       For many developers this may be the single most difficult aspect
-      of free software development but it is an essential one. It is
-      easy to become fired up by an idea and be caught up in the
+      of free software project managment, but it is an essential one. It is
+      easy to become fired up by an idea and get caught up in the
       momentum and excitement of a new project. It is often extremely
       momentum and excitement of a new project. It is often extremely
-      difficult to do but, it is important that any free software
-      developer remember that the best interests of the free software
+      difficult to do, but it is important that any free software
+      developer remembers that the best interests of the free software
       community and the quickest way to accomplish your own project's
       goals and the goals of similar projects can often be
       accomplished by <emphasis>not</emphasis> starting a new
       community and the quickest way to accomplish your own project's
       goals and the goals of similar projects can often be
       accomplished by <emphasis>not</emphasis> starting a new
     criteria, you can still go ahead. I thought <quote>gnubile</quote>
     was one of the best I'd heard for a free software project ever and
     I still talk about it long after I've stopped using the
     criteria, you can still go ahead. I thought <quote>gnubile</quote>
     was one of the best I'd heard for a free software project ever and
     I still talk about it long after I've stopped using the
-    program. However, if you can flexible on the subject, listen to
+    program. However, if you can be flexible on the subject, listen to
     Orchard's advice. It might help you.
    </para>
   </sect2>
     Orchard's advice. It might help you.
    </para>
   </sect2>
      brings up the question of <quote>Open Source Software</quote> and
      the debate over the terms <quote>Open Source Software</quote> and
      <quote>Free Software</quote>. However, because I've written the
      brings up the question of <quote>Open Source Software</quote> and
      the debate over the terms <quote>Open Source Software</quote> and
      <quote>Free Software</quote>. However, because I've written the
-     Free Software Development HOWTO and not the Open Source
-     Development HOWTO, my own allegiances in this argument are in the
-     open.
+     Free Software Project Management HOWTO and not the Open Source
+     Software Project Management HOWTO, my own allegiances in this
+     argument are in the open.
     </para>
 
     <para>
     </para>
 
     <para>
      Software Foundation and the GNU Project, the
      <acronym>GPL</acronym> is the license for the Linux kernel,
      GNOME, Emacs, and the vast majority of GNU/Linux software. It's
      Software Foundation and the GNU Project, the
      <acronym>GPL</acronym> is the license for the Linux kernel,
      GNOME, Emacs, and the vast majority of GNU/Linux software. It's
-     the obvious choice but I believe it is a good one. Any BSD
+     the obvious choice but I also believe it is a good one. Any BSD
      fanatic will urge you to remember that there is a viral aspect to
      the <acronym>GPL</acronym> that prevents the mixture of
      <acronym>GPL</acronym>'ed code with non-<acronym>GPL</acronym>'ed
      fanatic will urge you to remember that there is a viral aspect to
      the <acronym>GPL</acronym> that prevents the mixture of
      <acronym>GPL</acronym>'ed code with non-<acronym>GPL</acronym>'ed
     <para>
      The text of the <acronym>GPL</acronym> offers <ulink
      url="http://www.gnu.org/copyleft/gpl.html#SEC4">a good
     <para>
      The text of the <acronym>GPL</acronym> offers <ulink
      url="http://www.gnu.org/copyleft/gpl.html#SEC4">a good
-     description</ulink> of mechanics of applying a license to a piece
-     of software. My quick checklist for applying a license includes:
+     description of the mechanics of applying a license</ulink> to a
+     piece of software. My quick checklist for applying a license
+     includes:
     </para>
 
     <para>
     </para>
 
     <para>
@@ -1126,7 +1149,7 @@ pages for more information and options.
      In addition to man pages and command-line help, there are certain
      files where people will look for documentation, especially in any
      package containing source code. In a source distribution, most of
      In addition to man pages and command-line help, there are certain
      files where people will look for documentation, especially in any
      package containing source code. In a source distribution, most of
-     these files can be stored in the root directory of the source
+     these files can be stored in the root directory of the source
      distribution or in a subdirectory of the root called
      <quote>doc</quote> or <quote>Documentation.</quote> Common files
      in these places include:
      distribution or in a subdirectory of the root called
      <quote>doc</quote> or <quote>Documentation.</quote> Common files
      in these places include:
@@ -1158,7 +1181,7 @@ pages for more information and options.
        install</quote> and touches on any unusual options or actions
        that may be necessary. For most relatively standard install
        procedures and for most programs, INSTALL files are as short
        install</quote> and touches on any unusual options or actions
        that may be necessary. For most relatively standard install
        procedures and for most programs, INSTALL files are as short
-       as possible are rarely over 100 lines.</para>
+       as possible and are rarely over 100 lines.</para>
        </listitem>
 
       </varlistentry>
        </listitem>
 
       </varlistentry>
@@ -1172,7 +1195,7 @@ pages for more information and options.
        changes you make to your program. The most simple way to
        maintain a CHANGELOG is to simply keep a file with the source
        code for your program and add a section to the top of the
        changes you make to your program. The most simple way to
        maintain a CHANGELOG is to simply keep a file with the source
        code for your program and add a section to the top of the
-       CHANGELOG with each release describing what has been, changed,
+       CHANGELOG with each release describing what has been changed,
        fixed, or added to the program. It's a good idea to post the
        CHANGELOG onto the website as well because it can help people
        decide whether they want or need to upgrade to a newer version
        fixed, or added to the program. It's a good idea to post the
        CHANGELOG onto the website as well because it can help people
        decide whether they want or need to upgrade to a newer version
@@ -1245,7 +1268,7 @@ pages for more information and options.
 
     <para>
      It doesn't hurt to distribute any documentation for your program
 
     <para>
      It doesn't hurt to distribute any documentation for your program
-     from your website (FAQs etc) with your program. Don't hesitate
+     from your website (FAQs etc) with your program. Don't hesitate to
      throw any of this in the program's tarball. If people don't need
      it, they will delete it. I can repeat it over and over:
      <emphasis>Too much documentation is not a sin.</emphasis>
      throw any of this in the program's tarball. If people don't need
      it, they will delete it. I can repeat it over and over:
      <emphasis>Too much documentation is not a sin.</emphasis>
@@ -1284,7 +1307,7 @@ pages for more information and options.
      Binary packages should always be distribution specific. If you
      can build binary packages against a current version of a major
      distribution, you will only make your users happy. Try to foster
      Binary packages should always be distribution specific. If you
      can build binary packages against a current version of a major
      distribution, you will only make your users happy. Try to foster
-     relationships with users or developers of large distributiosn to
+     relationships with users or developers of large distributions to
      develop a system for the consistent creation of binary
      packages. It's often a good idea to provide RedHat
      <acronym>RPM</acronym>'s (.rpm), Debian deb's (.deb) and source
      develop a system for the consistent creation of binary
      packages. It's often a good idea to provide RedHat
      <acronym>RPM</acronym>'s (.rpm), Debian deb's (.deb) and source
@@ -1322,7 +1345,7 @@ pages for more information and options.
     <para>
      I'd love to devote more space in this HOWTO to CVS because I love
      it (I even use CVS to keep versions straight on this HOWTO!) but
     <para>
      I'd love to devote more space in this HOWTO to CVS because I love
      it (I even use CVS to keep versions straight on this HOWTO!) but
-     I think it falls outside the scope of this document and should
+     I think it falls outside the scope of this document and should have
      (already has) its own HOWTO.
     </para>
 
      (already has) its own HOWTO.
     </para>
 
@@ -1894,7 +1917,7 @@ pages for more information and options.
 <!-- Section2: otherdev -->
 
   <sect2 id="otherdev">
 <!-- Section2: otherdev -->
 
   <sect2 id="otherdev">
-   <title>Other Development issues</title>
+   <title>Other Project Management issues</title>
    <para>
     There are more issues surrounding interaction with developers in a
     free software project that I can not touch on in great detail in a
    <para>
     There are more issues surrounding interaction with developers in a
     free software project that I can not touch on in great detail in a
@@ -1946,18 +1969,19 @@ pages for more information and options.
      freeze in effect.
     </para>
    </sect3>
      freeze in effect.
     </para>
    </sect3>
+  </sect2>
 
 
-   <sect3>
-    <title>Forking</title>
+   <sect2>
+    <title>Forks</title>
     <para>
     <para>
-     Forks are like the most extreme version of a branch. A fork is
-     when a group of developers takes code from a free software
-     project and actually starts a brand new free software
-     project with it. The most famous example of a fork was between Emacs and
-     XEmacs. Both emacsen are based on an identical code-base
-     but for technical, political, and philosophical reasons,
-     development was split into two projects which now compete with
-     each other.
+     I wasn't sure about how I would deal with forking in this
+     document (or if I would deal with forking at all). A fork is when
+     a group of developers takes code from a free software project and
+     actually starts a brand new free software project with it. The
+     most famous example of a fork was between Emacs and XEmacs. Both
+     emacsen are based on an identical code-base but for technical,
+     political, and philosophical reasons, development was split into
+     two projects which now compete with each other.
     </para>
 
     <para>
     </para>
 
     <para>
@@ -1977,7 +2001,6 @@ pages for more information and options.
      absolutely unresolvable, I recommend Fogel's book as a good place
      to start.
     </para>
      absolutely unresolvable, I recommend Fogel's book as a good place
      to start.
     </para>
-   </sect3>
   </sect2>
  </sect1>
 
   </sect2>
  </sect1>
 
@@ -2053,7 +2076,7 @@ pages for more information and options.
    to try and be as responsive as possible. A solid knowledge of the
    situation recounted above is any free software developer's best tool
    for shifting his development or leadership style to fit the unique
    to try and be as responsive as possible. A solid knowledge of the
    situation recounted above is any free software developer's best tool
    for shifting his development or leadership style to fit the unique
-   process of free software development. This chapters will try and
+   process of free software project management. This chapters will try and
    introduce some of the more difficult or important points in any
    projects interactions with users and give some hints on how to
    tackle these.
    introduce some of the more difficult or important points in any
    projects interactions with users and give some hints on how to
    tackle these.
@@ -2259,7 +2282,7 @@ pages for more information and options.
     <para>
      It should not come as any surprise that the key element to any
      support infrastructure is good documentation. This topic was
     <para>
      It should not come as any surprise that the key element to any
      support infrastructure is good documentation. This topic was
-     large covered in <xref linkend="documentation"> and will not be
+     largely covered in <xref linkend="documentation"> and will not be
      repeated here.
     </para>
    </sect3>
      repeated here.
     </para>
    </sect3>

Benjamin Mako Hill || Want to submit a patch?