Date: Tue, 25 Dec 2012 18:03:26 +0000 (UTC) From: Benjamin Kaduk <bjk@freebsd.org> To: Lowell Gilbert <lgfbsd@be-well.ilk.org> Cc: freebsd-doc@freebsd.org Subject: Re: [freebsd-doc] Re: confusing sentence in hardware notes boilerplate Message-ID: <alpine.BSF.2.00.1212251740440.95558@freefall.freebsd.org> In-Reply-To: <44ehie9l2c.fsf_-_@lowell-desk.lan> References: <alpine.BSF.2.00.1212242202380.95209@freefall.freebsd.org> <20121225001355.GC16584@whisperer.chthonixia.net> <44ehie9l2c.fsf_-_@lowell-desk.lan>
next in thread | previous in thread | raw e-mail | index | archive | help
[reintroducing the patch so as to get the current version of the text for
reference]
Index: article.xml
===================================================================
--- article.xml (revision 244663)
+++ article.xml (working copy)
@@ -53,7 +53,7 @@
<para>This document contains the hardware compatibility notes for
&os; &release.current;. It lists the hardware platforms
supported by &os;, as well as the various types of hardware
- devices (storage controllers, network interfaces, and so on),
+ devices supported (storage controllers, network interfaces, and so on),
along with known working instances of these devices.</para>
</sect1>
On Tue, 25 Dec 2012, Lowell Gilbert wrote:
> Joe Altman <freebsd@chthonixia.net> writes:
>
>> On Mon, Dec 24, 2012 at 10:08:11PM +0000, Benjamin Kaduk wrote:
>>> I was going over the various release notes documents to do some editing,
>>> and spent entirely too much time trying to understand a sentence at the
>>> top of the hardware notes, which has been there since r172098 by bmah in
>>> 2007. I think that adding a word per below helps the readability, but I
>>> am no longer an impartial reader (having read the sentence too much).
>>> Thoughts?
>>
>> I try to refrain from using the same word more than once, when they are
>> in proximity. To me, adding "supported" as you propose is such.
>> Additionally, the phrase "...known working instances..." seems to
>> re-state the word "supported".
>
> I agree. It's not just awkward, it could be confusing, because a reader
> might assume that the repetition had semantic content, and read
> something into the sentence that wasn't there.
Well, I wanted to add semantic content. My response to reading the
current (unpatched) text is to say "hardware devices that what?".
The intent is clearly that these hardware devices are those supported, but
at least to me, reading the sentence is confusing.
>> OTOH, it could be written:
>>
>> This document lists the supported hardware platforms and devices such as
>> storage controllers, network interfaces, and so on, for &os;
>> &release.current;.
>
> That's not bad. To my ear, it's even a bit of an improvement on the
> original.
The original tries harder to make a distinction between hardware platforms
(e.g., i386, amd64, arm, etc.) and peripheral devices which may be
attached to a particular instance of such a platform. I do not think that
merging them together as having near-equal importance in the list is
necessarily the best choice. I guess I will ponder more extensive
rewordings, then.
-Ben
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1212251740440.95558>