[freebsd-doc] Re: confusing sentence in hardware notes boilerplate

[Benjamin Kaduk]

[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 at 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