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

[Warren Block]

On Tue, 25 Dec 2012, Joe Altman wrote:

> On Tue, Dec 25, 2012 at 06:03:26PM +0000, Benjamin Kaduk wrote:
>> [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>
>>
>>
> <snip>
>>
>>  but at least to me, reading the sentence is confusing.
>
> I agree; as phrased, it is confusing. It is confusing due to repetition,
> among other things. The repetition is perhaps not obvious, because the
> words change to express the same thing(s).
>
> Sometimes, it is useful to "tell them what you are going to tell them;
> tell them; and then tell them what you told them." but I think that rule
> is usefully when reserved for papers; not sentences nor paragraphs. The
> sentence or paragraph is where one "...tells them...".
>
>>>> This document lists the supported hardware platforms and devices such as
>>>> storage controllers, network interfaces, and so on, for &os;
>>>> &release.current;.
>
> As written, the word hardware is applied to both platforms and devices;
> and peripherals is contained (or implied) in the examples following
> "...such as...: so I think my proposal obtains what is sought.
>
>> I do not think that merging them together as having near-equal
>> importance in the list is
>
> IMO, importance is not implied by proximity. Proximity, in this case, is
> related to brevity.
>
>> I guess I will ponder more extensive rewordings, then.
>
> More words do not necessarily increase transparency or, more accurately,
> meaning. They can, however, tend to create an opacity that interferes
> with obtaining meaning from text. IMO.
>
> Perhaps this:
>
> This document lists the supported hardware platforms (Intel, AMD,
> etcetera) and devices (storage controllers, network interfaces, and
> other peripherals) for &os; &release.current;.

Not bad.  The problem with the original is that it's trying to jam three 
things into one sentence.  It seems unnecessary to say that it will 
mention known working instances; just mention them.  So:

   Hardware platforms and devices like storage controllers and network
   interfaces supported by &os; &release.current; are listed in this
   document.