Date: Tue, 06 Apr 1999 10:20:04 -0600 From: Sean Kelly <kelly@plutotech.com> To: Nik Clayton <nik@nothing-going-on.demon.co.uk> Cc: doc@FreeBSD.ORG Subject: Re: Organisation change for the Handbook Message-ID: <370A3434.26DB3045@plutotech.com> References: <19990405234615.B6083@catkin.nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Right, now that we've distracted people away from the handbook reorgani[sz]ation, let's give it another go. I just want to reiterate some of my views from last time, change some, and add some new ones: > The basic idea is simple. The Handbook has grown fairly organically, and > can be reorganised. Merely because we can do a thing does not mean we must do that thing! (Bonus points to whoever recognizes the line and the movie.) But, in this case, the organic development was good in order to pound out a handbook. Now that we've got a sizeable amount of material, I agree that it's time to put it into a coherent structure. > If necessary, people can maintain their own books out of the > main FreeBSD doc tree, while still maintaining the FreeBSD look and feel and > integration with the rest of the docs (if they want to, of course). They better ... or else! :-) > The Handbook's target audience needs to be understood. The Handbook should > be catering for the spectrum of people who, at one end, have never heard of > Unix or FreeBSD before through to those people who are very familiar with > FreeBSD, but who need a useful reference, or want to know as much as > possible about a topic they haven't yet covered (for example, printing). Writing and/or reorganizing for an audience that exists at both ends of the spectrum is going to be a challenge. Knuth failed to do this effectively at all in his "TeXBook." We know one approach to avoid, at least. But is there a decent approach? > This is likely to yield quite a schizophrenic document unless tackled > carefully. Uh, I basically just said that. :-) > The gist of my proposal is to split the Handbook up in to a number of > smaller books, containing between 70-150 'pages'. These would then truly be > *hand*books. Each book should tackle one topic, and not repeat information > from one of the other books. For example, if a book's topic requires that > the reader reconfigure their kernel (for example, Firewalls), they should be > directed to the appropriate part of the "Configuring FreeBSD" book, instead > of repeating that information there. I mostly agree. In particular, kernel configuration is one of out better chapters in the current handbook. Yet some amount of kernel configuration appears in nearly all the other chapters: in networking on setting up the kernel with an Ethernet controller; in printing on setting up the kernel for parallel ports; etc. I think the terminology is just tripping me up, here: are these really separate books? Will these be toplevel Docbook "book" elements? I'm wondering if there exists enough material in each book to warrant a book, and thence a collection for all of our documentation. > [ new organization ] Okay, I'm warming up to the idea now. In particular, "Unix Basics" ought to be its own book. A Unix expert doesn't need all that extra material if s/he just wants to know how to install FreeBSD. Some of the material for "the text console" does exist "off-site." I remember someone writing a tutorial on setting up fonts, mouse, etc. Does anyone have the URL? Finally, don't forget that we'll need a separate book that's a compiled index to the whole collection. Best, --Sean To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?370A3434.26DB3045>