Date: Thu, 15 Apr 1999 23:08:02 +0100 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: Nik Clayton <nik@nothing-going-on.demon.co.uk>, Greg Lehey <grog@lemis.com>, FreeBSD Documenters <doc@FreeBSD.ORG>, "Robert A. Bruce" <rab@cdrom.com> Subject: Re: Publishing the FreeBSD handbook Message-ID: <19990415230802.A2444@catkin.nothing-going-on.org> In-Reply-To: <19990414183018.D28429@caamora.com.au>; from jonathan michaels on Wed, Apr 14, 1999 at 06:30:18PM %2B1000 References: <19990412125145.J2142@lemis.com> <19990412212213.B9344@catkin.nothing-going-on.org> <19990414183018.D28429@caamora.com.au>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Apr 14, 1999 at 06:30:18PM +1000, jonathan michaels wrote: > On Mon, Apr 12, 1999 at 09:22:14PM +0100, Nik Clayton wrote: > > 1. Does the Handbook need a 6 month release cycle? The majority of > > the content doesn't change that much in 6 months. Wouldn't a > > threshold of "changes made since last printing" make more sense, > > perhaps with a minimum 6 month wait between prints. > > put anotehr way .. we just went from teh v2 style to v3 style > of doing things. that is their was some significant diferences > between teh way tings in general were done. > > wouldn't it be better of do a print after this level of change > was delivered in teh body of freebsd. That's pretty much what I was thinking. Doubtless we'll be flexible in these things. > > 2. What's the Walnut Creek reaction been to my ideas about splitting > > the Handbook up into smaller books? After "FreeBSD in 21 days" > > gets done that's my next big project. If the Handbook suddenly > > becomes 12 or 15 smaller handbooks in 8 or 9 months time that's > > obviously going to affect whatever they're thinking of. > > do we really need that many handbookettes, so to speak. I think so. . . > harking back tot eh installation guide discussion, don't we (as > a group) really only need, > > how to install and upgrade freebsd > > how to trouble shoot teh various sybsystems that make up teh > whole. Yeah. But each 'sub-system' could have 100-150 pages written about it. Printing, for example. Or the nuances of setting up e-mail (sendmail, qmail, postfix, majordomo, spam handling, procmail, . . .) [...] > nearly forgot .. a manpages of teh the specifically freebsd, > berkeley unix pages and a selection of teh most usefull to get > a broken system back onto ists hard disk and running. Yep. That covers the users. How about the developers? I'd love to see 100-150 pages about writing device drivers for FreeBSD, perhaps tackling one of the existing ones (sio, nlpt?) and showing how it does what it does, and why. "Writing a FreeBSD KLD", that sort of thing, too. All this is some way off. But some sort of framework for it to happen in is a good thing. > this is waht 3 at teh most and would also be a sort of > heterogenius whole .. having dozens of books on teh desktop is > a bloody nuisance at teh best of times. being able to reach fro > a relevant text makes fro far easier usages and that > ;satisfyingly warm fuzzy glow when you have sloved teh problem > quickly elegantly and teh minimun of disruption you yor desk > top boo collection. I sort of agree about this, but it does depend on what you're doing, and what level you're at. For example, it's been a long time since I set up a FreeBSD printer, so the Handbook section is great for me, since it covers just about everything I would need. If it's the sort of thing I do every month then I likely just need bullet points to remind what I'm supposed to be doing. I think there's room for both approaches. [...] > > This could well be a case of throwing $$$ at the problem. > > this is a noce position t be in, but throwing money at a > probelm never solved teh probelm, all that this aproceh does is > soakup teh available funds while they are available and tehn > when teh taps are obout to be turned off the real solutions > appear. I was making the distinction between relying on volunteer effort, and having someone paid to do it. To use me as an example, my FreeBSD efforts are (of necessity) restricted to about 4 hours a night, 4 or (maybe) 5 nights a week (less on a bad week). This limits the amount I can do. The other 8 or 9 hours each day are spent on my paying job. If I was being paid to do the Doc. Proj. stuff I'd get a lot more done (more accurately, all the stuff I want to do would get done faster). Incidentally, this should not be read as a plea for FreeBSD Inc. to start paying me. I doubt they could match what I'm currently on. But suppose that there's a glaring ommission in the docs -- I'd be happy to see money spent on paying a qualified author to write that section. > > > 3. Add an index, and generally improve the format. I'm planning to > > > do this myself, but if anybody else wants to join in (or even > > > take over), I'll be more than happy. > > > > Take a look around http://www.docbook.org/, in particular the bits that > > talk about how you can automatically generate an index. > > automatically generated indexes are pathetically bad, it would > have to be an execptionally good ai sequence or one of thse > fuzzy logic implemantation that can spew out a primliminary > cut. but, then a human would have to go through and check teh > references and their relevance. Ah ha! For this we have DocBook. More specifically, we have the <indexterm> element, which lets you indicate which words should appear in the index (and other cool stuff). Of course, someone's got to go through the text indicating what should and shouldn't be in the index, but we do have a defined way of doing it that avoids the problems you speak about. > cross referencing teh indvidual index entries would also make > for amore usefull index, as opposed to a simple word amd it > apperance type of list. We can do that too! > this is why i dislike online/electronic documentation, unless > it is in a wais accessable fromat, now thats indexing.. at work. Don't know about a WAIS index, although it should be possible. . . > > For emoticons, look for <!-- smiley --> in the SGML source. It was one > > of the things I noted when I was going through it. I haven't decided yet > > whether to remove them, or use entities: > > coming from my corner of teh world, i think that they are a > waste of effort, and dangerious. not everybody 'understands' or > pareciactes teh value of thes scratches and prush strokes. may > nisunderstands can be easily avioded by l;eaving thse silly > tings out. I tend to agree, but figured that this would be a very small, but very controversial change to make to the Handbook, so I left them in. The new set of handbooks will have a style guide that probably either says "Don't do them" or "Do them like this, so we can pull them out automatically if necessary". > smiles are ok fr thse still in grade school learning who to > read and write, tehy have littel place in a referenntial text. > des it really matter of teh scsi card has a smily tacked on to > its config stream ? I agree. If you haven't already, subscribe to alt.folklore.urban. They take exactly that attitude towards them in there. [format] > > I think I've grokked the solution to the main problem you've been having > > (which I'll go through in a private message). If it works for you, I'll > > commit it. > > ummm, why change sometint that most peple are familiar with and > works so well, fro at least this sometimes very slow user. It won't (as such). The idea is that the content will contain some additional hints so that the formatting stuff can make more intelligent decisions about how to format it. This *will not* include abusing markup to try and get a particular format effect. I hope that answers everything. As ever, if you (or anyone else) has questions, please post 'em. N -- Bagel: The carbohydrate with the hole 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?19990415230802.A2444>