Date: Tue, 30 Jan 96 16:30:20 MET From: Greg Lehey <lehey.pad@sni.de> To: kelly@fsl.noaa.gov (Sean Kelly) Cc: doc@freebsd.org Subject: Re: What printed documentation do we need? Message-ID: <199601301534.QAA05327@nixpbe.pdb.sni.de> In-Reply-To: <9601301511.AA00890@emu.fsl.noaa.gov>; from "Sean Kelly" at Jan 30, 96 8:11 am
next in thread | previous in thread | raw e-mail | index | archive | help
Hmmm. I haven't been replying to individual messages, mainly because I haven't had time, but I think enough has gone by for me to reassert my position. Some of what follows doesn't directly relate to this message, but bear with me. First, the book "Installing FreeBSD" is almost ready to go to the printers. It will contain much of the stuff people have been asking for, including, of course, how to install FreeBSD, but also a lot of stuff that people need to find their bearings when getting used to FreeBSD, such as what the devices are called, and where to find further documentation. My question here was basically related to what *other* docs we need. Now on to your message: >>>>>> "Greg" == Greg Lehey <lehey.pad@sni.de> writes: > > Greg> My thoughts are that we should print completely different > Greg> manuals describing software which is not described in these > Greg> manuals. > > I tend to agree with you here. There is a lot of material in the USD > and PSD that could give FreeBSD a big `boost' onto bookshelves---but I > still find them to be somewhat terse in some places, outdated in > others. I think the usable stuff is worth including, certainly if it isn't covered by an AT&T copyright. If it *is*, it doesn't mean it's off limits, it might just mean that somebody has to approach AT&T and get permission. Before we worry about what that might entail, we want to consider what's even worth thinking about. I don't have the books handy, but a description of how to use ed is probably not the sort of thing we want to include. A description of how to use gdb is, IMHO, very desirable, but it would be nice if it were a little more up-to-date than the stuff in 4.4BSD Lite. > In other words, Linux users would still point and laugh. Hmm. Some will do that anyway. But do they have justification? The great advantage of the man pages is that we can get them printed Real Soon Now, and thus they will be reasonably up to date. As you say below, the Linux crowd can't say as much of many of their books. > What I really want are FreeBSD books written from scratch by FreeBSD > people. I'd like to write such a book. Go for it! > As someone who's authored, Greg, how much time does such an endeavor > take? I remember Terry Lambert's analysis of 2600 hours or some such > figure. The inevitable conclusion: by the time you've finished the > book, it's out of date by three or four OS releases---not that THAT > stops Linux books. I haven't seen Terry's analysis, but it looks like a ballpark figure. I started writing PUS in mid-1992, and it took me until early 95 to supply a final draft. I got a bit side-tracked in the middle, but I don't think I can write a good, really polished book in less than about 8 months, even after the (significant) learning experience of the first book. I wrote the Installing book in 3 months, but: - it's not that polished - it's not that long - I stole a lot from the handbook The real problem I see every time is getting the structure right. You can know what you want to say, you can know how to say it, you can say it, but then you just have a brain dump. In my experience, the formatting is more than 50% of the work. Greg
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199601301534.QAA05327>