From owner-freebsd-doc@FreeBSD.ORG Wed Dec 26 05:10:31 2012 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id E81DFF5F for ; Wed, 26 Dec 2012 05:10:31 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 9742A8FC0A for ; Wed, 26 Dec 2012 05:10:30 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.5/8.14.5) with ESMTP id qBQ5ANEx055468; Tue, 25 Dec 2012 22:10:23 -0700 (MST) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.5/8.14.5/Submit) with ESMTP id qBQ5AMBg055465; Tue, 25 Dec 2012 22:10:23 -0700 (MST) (envelope-from wblock@wonkity.com) Date: Tue, 25 Dec 2012 22:10:22 -0700 (MST) From: Warren Block To: Joe Altman Subject: Re: [freebsd-doc] Re: confusing sentence in hardware notes boilerplate In-Reply-To: <20121225185408.GA19555@whisperer.chthonixia.net> Message-ID: References: <20121225001355.GC16584@whisperer.chthonixia.net> <44ehie9l2c.fsf_-_@lowell-desk.lan> <20121225185408.GA19555@whisperer.chthonixia.net> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.2.7 (wonkity.com [127.0.0.1]); Tue, 25 Dec 2012 22:10:23 -0700 (MST) Cc: freebsd-doc@freebsd.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 26 Dec 2012 05:10:32 -0000 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 @@ >> 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. >> >> >> > >> >> 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.