RFC: additions to the article "problem-reports"

[Simon L. Nielsen]

On 2003.05.08 18:51:41 -0500, Mark Linimon wrote:
> While working on my project to classify ports PRs in the database,
> I've come across more than my fair share of PRs that are really
> badly written.  Although the problem-reports article touches on
> this to some degree, I really feel that some of the most obvious
> mistakes bear further explanation.
> 
[CUT]
> 
> In any case I think this is a necessary, but probably insufficient,
> change for the documentation, and I'd like to see what other
> people think.  Consider it a starting point.

There were a few markup errors but considering that you havn't tried to
build it I actually think it was very few :-) - Patch to be applyed
after your patch should be attached.

You mention the subject of the pr but actually this is called Synopsis
when using send-pr(1) so I think that you should use that term instead.

Other than that I really like the change and I think the tips are good.

Nice work!

Btw. if you want to see how it looks build I just put it at
http://simon.nitro.dk/freebsd/files/misc/pr-article-with-tips.html .

-- 
Simon L. Nielsen
-------------- next part --------------
--- article.sgml	Fri May  9 02:02:14 2003
+++ article.sgml.sln	Fri May  9 02:16:16 2003
@@ -234,7 +234,7 @@
 	  <para><emphasis>If you are a maintainer, say so</emphasis>
             By convention, if you are maintaining a part of the
             source code (for instance, a port), put the string
-            <literal>[maintainer update]</listeral> at the
+            <literal>[maintainer update]</literal> at the
             beginning of your Subject: line.</para>
         </listitem>
       
@@ -246,7 +246,7 @@
             running (there is a place to put that, see below);
             which architecture you are running on;
             whether you are running from a release CDROM, or from
-            a system maintained by &cvsup.1; (and, if so, how
+            a system maintained by &man.cvsup.1; (and, if so, how
             recently you updated); and, if a kernel problem,
             if you have read <literal>src/UPDATING</literal>
             (someone is guaranteed to ask).  You do not necessarily
@@ -276,7 +276,7 @@
             Although this has already been mentioned above, it bears
             repeating here.  It only take a minute or two to use the
             web-based search engine.  (Of course, everyone is guilty of
-            forgetting to do this now and then.)
+            forgetting to do this now and then.)</para>
         </listitem>
       
 	<listitem>
@@ -298,7 +298,7 @@
             thing to keep in mind at all times on Open Source
             projects.</para>
         </listitem>
-      
+      </itemizedlist>
     </section>
 
     <section>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030509/473558c7/attachment.sig>