From owner-freebsd-doc@FreeBSD.ORG Tue Dec 25 18:52:53 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 CEE39F33 for ; Tue, 25 Dec 2012 18:52:53 +0000 (UTC) (envelope-from freebsd@chthonixia.net) Received: from www5.pairlite.com (www5.pairlite.com [64.130.10.15]) by mx1.freebsd.org (Postfix) with ESMTP id A26EE8FC0C for ; Tue, 25 Dec 2012 18:52:53 +0000 (UTC) Received: from whisperer.chthonixia.net (unknown [184.152.30.105]) by www5.pairlite.com (Postfix) with ESMTPSA id DD7FE2E2DD for ; Tue, 25 Dec 2012 13:52:51 -0500 (EST) Date: Tue, 25 Dec 2012 13:54:08 -0500 From: Joe Altman To: freebsd-doc@freebsd.org Subject: Re: [freebsd-doc] Re: confusing sentence in hardware notes boilerplate Message-ID: <20121225185408.GA19555@whisperer.chthonixia.net> References: <20121225001355.GC16584@whisperer.chthonixia.net> <44ehie9l2c.fsf_-_@lowell-desk.lan> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.21 (2010-09-15) 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: Tue, 25 Dec 2012 18:52:53 -0000 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;. Best regards, Joe