From owner-freebsd-doc@FreeBSD.ORG Thu May 8 17:55:10 2003 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 105B337B401 for ; Thu, 8 May 2003 17:55:10 -0700 (PDT) Received: from sixshooter.v6.thrupoint.net (sixshooter.v6.thrupoint.net [65.242.152.6]) by mx1.FreeBSD.org (Postfix) with ESMTP id 5FB2E43FAF for ; Thu, 8 May 2003 17:55:09 -0700 (PDT) (envelope-from jpb@sixshooter.v6.thrupoint.net) Received: from sixshooter.v6.thrupoint.net (localhost.v6.thrupoint.net [127.0.0.1]) by sixshooter.v6.thrupoint.net (Postfix) with ESMTP id B744B4CFB for ; Thu, 8 May 2003 20:55:08 -0400 (EDT) Received: (from jpb@localhost)h490t8cO006022 for freebsd-doc@freebsd.org; Thu, 8 May 2003 20:55:08 -0400 (EDT) Date: Thu, 8 May 2003 20:55:08 -0400 From: Jim Brown To: freebsd-doc@freebsd.org Message-ID: <20030509005508.GB5716@sixshooter.v6.thrupoint.net> Mail-Followup-To: freebsd-doc@freebsd.org References: <200305081851.41118.linimon@lonesome.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <200305081851.41118.linimon@lonesome.com> User-Agent: Mutt/1.4.1i Subject: Re: RFC: additions to the article "problem-reports" X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 09 May 2003 00:55:10 -0000 * Mark Linimon [2003-05-08 19:48]: > 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. > > So here's a rough draft of a new section "Tips and tricks for writing > a good Problem Report" to be applied to > /usr/doc/en_US.ISO8859-1/articles/problem-reports/article.sgml. > A few things to note first: > > 1. I've never written SGML before, and I haven't verified this > text's correctness. (Maybe someday I'll learn how to do that, > but right now I am in the middle of this other hackathon, see ... :-) ) > > 2. I've never written this large a chunk of FreeBSD documentation > before, so I won't be offended if either the style is found wanting, > or, in this case, my choice of where to put the changes. (No place > seemed exactly correct.) > > 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. > > Mark Linimon (aka "mcl") > Nice job. Fits very neatly into the original document. Thanks to Simon for posting. jpb ===