Date: Thu, 6 Dec 2001 15:59:02 -0700 From: Chad David <davidc@acns.ab.ca> To: Robert Watson <rwatson@FreeBSD.org> Cc: Chad David <davidc@acns.ab.ca>, Luigi Rizzo <rizzo@aciri.org>, 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> In-Reply-To: <Pine.NEB.3.96L.1011206174402.21187Q-100000@fledge.watson.org>; from rwatson@FreeBSD.org on Thu, Dec 06, 2001 at 05:46:35PM -0500 References: <20011206154216.A94670@colnta.acns.ab.ca> <Pine.NEB.3.96L.1011206174402.21187Q-100000@fledge.watson.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20011206155902.A94788>