From owner-freebsd-doc Tue Feb 19 13:52:57 2002 Delivered-To: freebsd-doc@freebsd.org Received: from rwcrmhc51.attbi.com (rwcrmhc51.attbi.com [204.127.198.38]) by hub.freebsd.org (Postfix) with ESMTP id 5D96C37B402 for ; Tue, 19 Feb 2002 13:52:49 -0800 (PST) Received: from bmah.dyndns.org ([12.233.149.189]) by rwcrmhc51.attbi.com (InterMail vM.4.01.03.27 201-229-121-127-20010626) with ESMTP id <20020219215248.KBXW2626.rwcrmhc51.attbi.com@bmah.dyndns.org>; Tue, 19 Feb 2002 21:52:48 +0000 Received: (from bmah@localhost) by bmah.dyndns.org (8.11.6/8.11.6) id g1JLqmU06263; Tue, 19 Feb 2002 13:52:48 -0800 (PST) (envelope-from bmah) Message-Id: <200202192152.g1JLqmU06263@bmah.dyndns.org> X-Mailer: exmh version 2.5 07/13/2001 with nmh-1.0.4 To: Tom Rhodes Cc: freebsd-doc@FreeBSD.ORG Subject: Re: docs/32578: [PATCH] for doc review In-reply-to: <200202192100.g1JL02q96051@freefall.freebsd.org> References: <200202192100.g1JL02q96051@freefall.freebsd.org> Comments: In-reply-to Tom Rhodes message dated "Tue, 19 Feb 2002 13:00:02 -0800." From: "Bruce A. Mah" Reply-To: bmah@FreeBSD.ORG X-Face: g~c`.{#4q0"(V*b#g[i~rXgm*w;:nMfz%_RZLma)UgGN&=j`5vXoU^@n5v4:OO)c["!w)nD/!!~e4Sj7LiT'6*wZ83454H""lb{CC%T37O!!'S$S&D}sem7I[A 2V%N&+ X-Image-Url: http://www.employees.org/~bmah/Images/bmah-cisco-small.gif X-Url: http://www.employees.org/~bmah/ Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Date: Tue, 19 Feb 2002 13:52:48 -0800 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org If memory serves me right, Tom Rhodes wrote: > The following reply was made to PR docs/32578; it has been noted by GNATS. > > From: Tom Rhodes > To: FreeBSD-gnats-submit@FreeBSD.org > Cc: > Subject: Re: docs/32578: [PATCH] for doc review > Date: Tue, 19 Feb 2002 15:54:42 -0500 (EST) Hi Tom-- My apologies in advance. I'm going to be brutally honest here, in hopes of making future doc PRs (from everybody, not just you) more effective. I'm going to say why I think a patch like this one is very difficult for a committer to work with. A subject line such as "[PATCH] for doc review" is all but useless because unless someone on the list knows exactly what docs/32578 refers to, they're probably just going to ignore it. If you can, keep the original subject line or some variation thereof (you must have had this information at one point). (To save a bunch of people having to look it up, the original PR had to do with changing the wording of the top-level page on the Web site.) > diff -ru en.old/index.xsl en/index.xsl > --- en.old/index.xsl Tue Feb 19 15:28:13 2002 > +++ en/index.xsl Tue Feb 19 15:52:40 2002 > @@ -224,7 +224,7 @@ > >

FreeBSD is an advanced operating system for > Intel ia32 compatible, DEC Alpha, and PC-98 architectures. > - It is derived from BSD UNIX, the version of UNIX developed at > + It is derived from BSD UNIX, the version of UNIX developed at This is a whitespace change. Please don't mix whitespace and content changes in the same diff. It makes it hard for translators, as well as people who are actually trying to review your change. > the University of California, Berkeley. > It is developed and maintained by > @@ -233,33 +233,36 @@ > platforms are in > various stages of development.

> > -

Cutting edge features

> +

FreeBSD has cutting edge features >

> The original complaint was that the bullets on the front page were missing parallel sentence structure. This change (taken in context) doesn't help this problem...in fact, it makes it worse. >

FreeBSD offers advanced networking, performance, security > and compatibility > features > today which are still missing in other operating systems, > even some of the best commercial ones.

> - > -

Powerful Internet solutions

> + > +

Industrial strength Networking h2> > Please make capitalization consistent. Either write "Industrial Strength Networking" or "Industrial strength networking". Is there some reason you wanted to change the wording? >

FreeBSD makes an ideal > Internet or Intranet > server. It provides robust network services under the heaviest > loads and uses memory efficiently to maintain good response > - times for thousands of simultaneous user processes. Visit our > + time for thousands of simultaneous user processes. Visit our > gallery for examples of > - FreeBSD powered applications and services.

> - > -

Run a huge variety of > - applications

> + FreeBSD powered applications, servers, networks, and other serv > ices.

> + > +

FreeBSD has access to hundreds of appli > cations > +

> With this change, we have two of the h2-level headings starting with "FreeBSD has", one that begins with "FreeBSD is", and the remainder are sentence fragments of some kind. Inconsistency like this is what the original PR was about. >

The quality of FreeBSD combined with today's low-cost, > high-speed PC hardware makes FreeBSD a very economical > alternative to commercial UNIX workstations. It is well-suited > - for a great number of both desktop and server > - applications.

> - > + for a great number of both desktop and server > + applications. > + Imagine an entire developement environment s/developement/development/ My spelling isn't perfect either, but please use a spelling checker if you're going to submit a doc patch. > + right at your finger tips, with support for almost all of t s/finger tips/fingertips/ > he major > + programming languages!.

> + Finish this sentence with an exclamation point or a period but not both, please. I'm generally of the opinion that exclamation points in technical writing look silly, but that's my personal opinion. Think "professional" here. But regardless of what you choose for ending punctuation, use one symbol only. >

Easy to install

> >

FreeBSD can be installed from a variety of media including Yes, it looks like I'm nitpicking. But if we as a project want to be taken seriously, we at least have to keep grammatical errors and misspellings out of our top-level Web page. This means *use* ispell, and *proofread* changes, before sending them in. To be honest, if I have the choice of working on a patch that needs to be fixed before applying and one that doesn't, I'll pick the latter almost any day. Thanks, Bruce. PS. Yes, it took me longer to write this message than it would have to fix the patch. I think of this as an investment which hopefully will pay off in future, high-quality PRs. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message