From owner-cvs-all Thu Dec 6 14:59:12 2001 Delivered-To: cvs-all@freebsd.org Received: from mail.acns.ab.ca (h24-64-56-135.cg.shawcable.net [24.64.56.135]) by hub.freebsd.org (Postfix) with ESMTP id 627B637B417; Thu, 6 Dec 2001 14:59:03 -0800 (PST) Received: from colnta.acns.ab.ca (colnta.acns.ab.ca [192.168.1.2]) by mail.acns.ab.ca (8.11.6/8.11.3) with ESMTP id fB6Mx3X10466; Thu, 6 Dec 2001 15:59:03 -0700 (MST) (envelope-from davidc@colnta.acns.ab.ca) Received: (from davidc@localhost) by colnta.acns.ab.ca (8.11.6/8.11.3) id fB6Mx2894812; Thu, 6 Dec 2001 15:59:02 -0700 (MST) (envelope-from davidc) Date: Thu, 6 Dec 2001 15:59:02 -0700 From: Chad David To: Robert Watson Cc: Chad David , Luigi Rizzo , cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org Subject: Re: cvs commit: src/share/man/man7 tuning.7 Message-ID: <20011206155902.A94788@colnta.acns.ab.ca> Mail-Followup-To: Robert Watson , Chad David , Luigi Rizzo , cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org References: <20011206154216.A94670@colnta.acns.ab.ca> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: ; from rwatson@FreeBSD.org on Thu, Dec 06, 2001 at 05:46:35PM -0500 Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG On Thu, Dec 06, 2001 at 05:46:35PM -0500, Robert Watson wrote: > > On Thu, 6 Dec 2001, Chad David wrote: > > > How is something like this? It isn't quite as broken out as it could > > be, mostly because I tried to use as much of the original text as > > possible. I have fixed a few spelling mistakes etc. but it still needs > > work. I did add a litte text around the keepalive section. > > > > The question I struggled with while putting this together was do we > > group by system (disk, memory, network etc.), or do we group by tunable > > section (filesystem layout etc., sysctl's and tunables, kernel config, > > etc.)? Now that I've gone through it all, I think it should be > > structured more like was suggested then how I updated it. By trying to > > group it by tunable section I ended up with some data spread all over > > the file. > > I think the proposed strategy of sorting by topic may be the best > approach--in a sense, I don't care so much about the vehicle by which I > optimize performance, as the effect of the optimization, or how it relates > to a problem I've identified. I considered it from the perspective of how easily I could find the information I was looking for. If I've identified the problem, I do not want to read the entire manual just to find the part about my problem; on the other hand, the document should flow if someone wants to read it from start to finish, without repeating itself over and over again. > > > Another question was if we wanted to maintain Matt's informal tone? > > Some terms like "network suds" give the manual a more playful feeling > > which I tried not to kill (although I did change a lot of 'I's to > > 'we's). > > I cleaned up a little of that in my recent commits, and I suspect > continuing to move gradually in the direction of formalism might be a good > thing. But maybe I'm old and dusty. One of the concerns I did have was > about the "currency" of the information: for example, the manpage advises > the reader not to use IDE tagged stuff. It should probably qualify such > statements with "at the time this document was written". These statements > have a tendency to get old fast, and not get updated for long periods of > time. This is one of my primary concerns with regard to all manual pages. For example I wrote the ucred.9 man page and then you came along ;). Other then staying very informed about all that is changing in FreeBSD I do not know how someone can keep these pages up to date. > > Robert N M Watson FreeBSD Core Team, TrustedBSD Project > robert@fledge.watson.org NAI Labs, Safeport Network Services > > -- Chad David davidc@acns.ab.ca ACNS Inc. Calgary, Alberta Canada To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message