Bug reporting documentation (issue 27)

git-svn-id: http://svn.osgeo.org/postgis/trunk@2789 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/doc/postgis.xml b/doc/postgis.xml
index 2e8ce49aaebcec69893d5bb86553367bda4393ec..25a194fbe80f522142b8168bde25d1c8c6e9f46e 100644 (file)
--- a/doc/postgis.xml
+++ b/doc/postgis.xml
@@ -6072,7 +6072,9 @@ z' = z </programlisting> This method is a subcase of
   </chapter>
 
   <chapter>
-    <title>Reporting Bugs</title>
+    <title>Reporting Problems</title>
+    <sect1>
+      <title>Reporting Software Bugs</title>
 
     <para>Reporting bugs effectively is a fundamental way to help PostGIS
     development. The most effective bug report is that enabling PostGIS
@@ -6082,19 +6084,71 @@ z' = z </programlisting> This method is a subcase of
     postgis_full_version()</code> [for postgis] and <code>SELECT version()</code>
     [for postgresql].</para>
 
-    <para>If you aren't using latest release, it's worth taking a look
+    <para>If you aren't using the latest release, it's worth taking a look
     at its <ulink url="http://postgis.refractions.net/CHANGES.txt">release
     changelog</ulink> first, to find out if your bug has already been fixed.</para>
 
     <para>Using the <ulink url="http://code.google.com/p/postgis/issues/list">PostGIS
     bug tracker</ulink> will ensure your reports are not discarded, and will
-    keep you informed on it's handling process. Before reporting a new bug
+    keep you informed on its handling process. Before reporting a new bug
     please query the database to see if it is a known one, and if it is please
     add any new information you have about it.</para>
 
     <para>You might want to read Simon Tatham's paper about <ulink
     url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report
     Bugs Effectively</ulink> before filing a new report.</para>
+    </sect1>
+    <sect1>
+      <title>Reporting Documentation Issues</title>
+
+        <para>The documentation should accurately reflect the features and
+        behavior of the software. If it doesn't, it could be because of a software bug or
+        because the documentation is in error or deficient.</para>
+
+        <para>Documentation issues can also be reported to the
+        <ulink url="http://code.google.com/p/postgis/issues/list">PostGIS bug tracker</ulink>.</para>
+
+       <para>If your revision is trivial, just describe it in a new bug tracker issue,
+        being specific about its location in the documentation.</para>
+
+       <para>If your changes are more extensive, a Subversion patch is definitely preferred.
+       This is a four step process on Unix (assuming you already have
+       <ulink url="http://subversion.tigris.org/">Subversion</ulink> installed):</para>
+
+        <orderedlist>
+          <listitem>
+
+           <para>Check out a copy of PostGIS' Subversion trunk. On Unix, type:</para>
+
+            <para><command>svn checkout http://svn.refractions.net/postgis/trunk/</command></para>
+
+           <para>This will be stored in the directory ./trunk </para>
+          </listitem>
+          <listitem>
+
+           <para>Make your changes to the documentation with your favorite text editor. On Unix, type (for example):</para>
+
+            <para><command>vi trunk/doc/postgis.xml</command></para>
+
+           <para>Note that the documentation is written in SGML rather than HTML,
+            so if you are not familiar with it please follow the example of the rest of the documentation.</para>
+
+          </listitem>
+          <listitem>
+
+           <para>Make a patch file containing the differences from the master copy of the documentation. On Unix, type:</para>
+
+            <para><command>svn diff trunk/doc/postgis.xml > doc.patch</command></para>
+
+          </listitem>
+          <listitem>
+
+            <para>Attach the patch to a new issue in bug tracker.</command></para>
+
+          </listitem>
+        </orderedlist>
+
+    </sect1>
   </chapter>
 
   <appendix id="release_notes">