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

[Joe Altman]

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;.

Best regards,

Joe