Date: Tue, 19 Feb 2002 13:52:48 -0800 From: "Bruce A. Mah" <bmah@FreeBSD.ORG> To: Tom Rhodes <darklogik@pittgoth.com> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: docs/32578: [PATCH] for doc review Message-ID: <200202192152.g1JLqmU06263@bmah.dyndns.org> In-Reply-To: <200202192100.g1JL02q96051@freefall.freebsd.org> References: <200202192100.g1JL02q96051@freefall.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <darklogik@pittgoth.com>
> 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 @@
>
> <p>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
> <a
> @@ -233,33 +233,36 @@
> <a href="{$base}/platforms/index.html">platforms</a> are in
> various stages of development.</p>
>
> - <h2><font color="#990000">Cutting edge features</font></h2>
> + <h2><font color="#990000">FreeBSD has cutting edge features</font
> ></h2>
>
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.
> <p>FreeBSD offers advanced networking, performance, security
> and compatibility
> <a href="{$base}/features.html">features</a>
> today which are still missing in other operating systems,
> even some of the best commercial ones.</p>
> -
> - <h2><font color="#990000">Powerful Internet solutions</font></h2>
> +
> + <h2><font color="#990000">Industrial strength Networking</font></
> h2>
>
Please make capitalization consistent. Either write "Industrial
Strength Networking" or "Industrial strength networking". Is there
some reason you wanted to change the wording?
> <p>FreeBSD makes an ideal
> <a href="{$base}/internet.html">Internet or Intranet</a>
> 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
> <a href="gallery/gallery.html">gallery</a> for examples of
> - FreeBSD powered applications and services.</p>
> -
> - <h2><font color="#990000">Run a huge variety of
> - applications</font></h2>
> + FreeBSD powered applications, servers, networks, and other serv
> ices.</p>
> +
> + <h2><font color="#990000">FreeBSD has access to hundreds of appli
> cations
> + </font></h2>
>
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.
> <p>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
> - <a href="{$base}/applications.html">applications</a>.</p>
> -
> + for a great number of both desktop and server
> + <a href="{$base}/applications.html">applications.</a>
> + 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!.</p>
> +
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.
> <h2><font color="#990000">Easy to install</font></h2>
>
> <p>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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200202192152.g1JLqmU06263>