Date: Tue, 25 Dec 2012 22:10:22 -0700 (MST) From: Warren Block <wblock@wonkity.com> To: Joe Altman <freebsd@chthonixia.net> Cc: freebsd-doc@freebsd.org Subject: Re: [freebsd-doc] Re: confusing sentence in hardware notes boilerplate Message-ID: <alpine.BSF.2.00.1212252153310.55388@wonkity.com> In-Reply-To: <20121225185408.GA19555@whisperer.chthonixia.net> References: <alpine.BSF.2.00.1212242202380.95209@freefall.freebsd.org> <20121225001355.GC16584@whisperer.chthonixia.net> <44ehie9l2c.fsf_-_@lowell-desk.lan> <alpine.BSF.2.00.1212251740440.95558@freefall.freebsd.org> <20121225185408.GA19555@whisperer.chthonixia.net>
next in thread | previous in thread | raw e-mail | index | archive | help
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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1212252153310.55388>