Rather than respond to everyone's message individually, I'm going to wrap them up and respond in this one. This is another long message I'm afraid. Sean Kelly pointed out that we really need to understand who the taregt audience are; obviously, the answer is everyone :-) I'm in broad agreement with Jordan about this. I envisage that the Handbook (that name is itself probably misleading) needs to cater for the spectrum of those people who are new to FreeBSD and Unix, through to people who are very familiar with it, but are looking for information about something they haven't yet needed to tackle (printing, for example). I don't think the Handbook should be catering for people for whom FreeBSD is their first exposure to any operating system. I think we should assume at least some familiarity with MS-DOS. Not to the batch programming level, but certainly the understanding that you type commands at the prompt, and that you need to press RETURN after each command. This may be less relevant now in the age of Windows. But I think if we aim at the truly new we'll bite off more than we can chew. If the Handbook is organised properly, "FreeBSD for the truly new" becomes a chapter that precedes all the others anyway. What will probably help is another chapter, "Differences from. . .", with sections for DOS, Linux, Solaris, SunOS, and any other OS' that people care to write about. My suggestions for breaking the Handbook up in to seperate DocBook s caused some comment. I'm still not sure if this is a good idea or not -- fortunately, once content is organised into chapters it's relatively easy to use those chapters in different frameworks, so I can experiment with this without causing undue problems for anyone else. The final decision on whether or not to do this can wait. [ 'section' in the following does not indicate a DocBook ] I think the Handbook can be broadly broken in to two large sections. The first section deals with the installation of FreeBSD, and getting the user familiar enough with it that they understand how it's configured (or at least where the configuration information is held and how to change it) and how to carry out relatively simple tasks (logging in, editing files, performing an orderly shutdown, shell scripts). The second section(s) detail how to carry out specific tasks using FreeBSD (printing, using a modem, connecting to the Internet) and so on. In the 'User's guide to the Handbook', users are told "Read the first section, which gets you up to speed with FreeBSD, and gives you the grounding you will need to understand the other sections. Then decide which task you want to carry out (printing, using your modem, connecting to the Internet) and locate the section that discusses that." The user then doesn't need to read the Handbook all the way through (in fact, is probably encouraged not to) but can go straight to those sections that deal with the task in hand. Only the first few sections have to be read through from start to finish in order to gain the overall understanding required. Occasionally, one of these sections might refer to one of the others. For example, the beginning of the PPP and SLIP sections would say "Please read the 'Using a modem with FreeBSD' section before carrying on." The rest of the PPP and SLIP sections could then assume that the user had correctly wired up their modem, had used 'tip' to connect to it, issued AT commands and so forth. That information wouldn't need to be repeated. I would expect each one of these second sections to conform to a similar style. Each would start with an overview explaining what that section covers, and what the user will be able to do when they have completed working through that section. Pre-requisites will be listed ("You must have a modem, configured and working (see the "Using a modem with FreeBSD" section). You must have an account with an Internet Service Provider. You must have read the previous sections about IP addresses, gateways, routing,. . .") The rest of the section then works through whatever that section is talking about, until the user has done whatever it is they want to do. In general, if the section requires hardware ("Printing", "Modems", "Ethernet". . .) then the installation and configuration of that hardware is covered first -- this should cover the physical installation of the hardware ("Plug in your ethernet card in accordance with the manufacturers instructions") and the configuration necessary to get FreeBSD to recognise the hardware ("Add the line "device ..." to your kernel config file and rebuild your kernel. If you don't know what this means then please read the "Configuring your kernel" section"). Then the software is covered. In some cases this might include several different applications. Finally, a "Further reading" section can cover books, magazines, web sites, and other parts of the Handbook that could be followed up on. This is why I think these *might* be better off as seperate books -- I'm familiar with FreeBSD, but have never needed to seriously delve into the Printing system. As and when I need to attach a printer to my FreeBSD box, I'd ideally just like to pick up the printing book, read through it, and do it. Thinking about this some more, I've made a few more changes to the layout. "Emulation" is now a part in its own right, and "Kernel debugging" and "FreeBSD Internals" become part of the "Code" chapter in the "Contributing to FreeBSD" part. A new part "Staying up to date with FreeBSD" rises from the flames of "Advanced Topics" (after all, to me, 'Printing' is an advanced topic -- the term is too nebulous to be meaningful). I've taken Eivind's suggestion, and pulled Security out into its own Part. The "Further reading" chapter for this part will include a reference to the firewall discussion in "Networking" (or perhaps that should be the other way round?). The "Configuring" part is really information about how you should go about configuring FreeBSD, rather than configuring it for a specific purpose. It's existence is so that other parts can handwave "Add this option to your kernel" or "Tweak this knob in your startup config file" and have somewhere to point people who don't know what this means. Of course, this part would be one of the mandatory "read this before reading on" parts. So I've pulled out the localisation and disk quota information. Localisation gets its own part, with chapters for Russian and German (and French, Spanish, . . .). Disk quotas go in a new "Monitoring and limiting users" part, which also covers process accounting (thanks to Sean for mentioning that one) and can talk about things like login.conf as well. Added "The committers guide" under "Contributing to FreeBSD". This is the "Welcome to FreeBSD travel. . ." message that new committers get when they sign up. It's funny, informative, and it might help remove some of the "FreeBSD committers are a closed group" myth. Incidentally, it's interesting to see that myth perpetuated at the Halloween MS leaked document . It's also worth searching that document and seeing the references to FreeBSD and code-forking. More specifically, the description of "Open Source (Apache-style)" sounds more like "Open Source (FreeBSD-style). Where was I? Oh yes, I was digressing :-) Rename the "Internet Communications" part to "TCP/IP Networking (Internet)". Move out most of the additional protocol discussion (SMTP, NTP, NFS). There's no point having half that information in here and half in some other chapter talking about the application itself. Instead, create an "Electronic Mail Servers" part, an "Electronic Mail Clients" part, a "File sharing" part, and a "Time/date synchronisation part". DNS is such an integral part of this it starts in this part with its own chapter. I've left DNS and NIS in here. It's (probably) the wrong place, but I'm not sure where else to put them. In "Electronic Mail Servers" split out the content by protocol, with an overview that explains what these protocols are and how they might be used. Then detail servers that can be used for these protocols. "Electronic Mail Clients" talks about MUAs. I think a nice touch would be to include some information about non-FreeBSD MUAs. The harried SysAdmin then has information on how to (for example) configure Eudora to fetch mail from a FreeBSD POP server. These two parts could be merged into one master "Electronic Mail" part, with chapters and sections for servers and clients. I'm not sure if this is a good idea, as you would then need to have two "Overview"s. I think there should only be one overview per part. "File sharing" (possibly called "Distributed Filesystems" instead?) talks about NFS, SMB (Samba), Coda and Appletalk (CAP, NetaTalk). "Time/date synchronisation" is for NTP. Should anyone have a tutorial on "How to make your own Stratum 0 time server using FreeBSD", this is where it would live. Pull "Contributors" out of "Contributing to FreeBSD" and in to the Appendices, next to the "FreeBSD Project Staff". Keep in mind most of these chapters will be empty to start with. I figure that's not so bad though, because they're (mostly) smaller, it's much easier when someone comes on the -doc mailing list and says "What can I do?", they can be pointed at one of these and say "We need volunteers to write these, please pick one." Eivind raised the issue of how making the Handbook a series of s would affect people who want to print it out. It shouldn't, except for things like page numbers changing. He makes the (IMHO) more interesting point about how it would affect people who want to print the Handbook for sale. Apart from giving them some extra work, it shouldn't. I envisage the Handbook's content being organised into files along chapter lines, with a master file that uses HTML entities to reference these chapters. You could have one master file that organised chapters into one book with many parts, and another that organises chapters into many books. What's even more interesting is the notion that people should take the handbook and sell it. I've been pondering this for a while, but haven't worked up the energy to kick off a discussion about it. Large parts of the Handbook are marked (c) the author that wrote them, with no explicit rights granted except to the Doc. Proj. This could (I believe) cause problems for anyone that wanted to simply re-print the Handbook. I'd be happier with a blanket copyright statement for the Handbook, and responses on file from the authors of particular sections saying that they assign whichever rights are necessary to FreeBSD Inc. The Handbook/Doc. Proj. web pages then need updating to mention this policy on new submissions. Sean said: > Again, the goals of the handbook need to be determined. A *hand*book is > not a set; yet a handbook of, say, 120 printed pages is a good thing to > have. Maybe what we should be after is a set, but where one of the > books is a handbook, written for the more experienced or more impatient > user (with just 10 pages on printing), and then a separate book that > covers each topic in excruciating detail (with a 100 page book on > printing). Then FreeBSD would compare well with HP/UX's and Sun's book > sets. FWIW, a reasonably recent generation of the RTF version of the Handbook yielded a 421 page RTF file (!) (at if you're interested). I don't think that's a 'handbook', but I think the new organistion would bring it down into 14 or 15 chunks of 30 pages each (some a bit more, some a bit less). That sounds more handbook sized to me. As to breaking things down for the impatient user, I'm hoping two things will do that; 1. Organising parts/books with an "Overview" section at the start. The impatient can probably skip it. 2. Removing a lot of the 'fluff' verbiage. By this I mean the sections that repeat information about how to (for example) become root, or how to add a kernel config option. Sue Blake's comment: > The first few times I read the Handbook, I read it from cover to cover > without any idea that some was unnecessary. The "easy" bits were as > incomprehensible to me as the advanced stuff so it seemed like it all > had to be conquered before installing. is hopefully tackled by strongly suggesting that the first few sections (intro to FreeBSD, installing, how to configure the system) be considered mandatory, with the other parts/books assuming this level of knowledge. This gives authors a hint as to the level of knowledge they can assume from their audience (if it's not in parts 1 or 2 you'll need to explain it) and only gives us one or two points where the documentation needs to be more 'newbie friendly' (i.e., the beginning sections). She also said: > I'd like to be able to pick up the handbook and instantly find what > an inexperienced new user needs without much searching, and get that > only to the level required for now (with links to more info of course) > and in a sequence that resembles the order in which it can be used. Hopefully you'll agree that the new structure covers this. As regards sequence, the user is (past the first 2 parts) free to choose which sequence they want to read things in -- they should be relatively self contained. More importantly, they're goal orientated. And also: > And the handbook must be readily available in a recognisably > Microsoft-friendly format if they are to read it before installing, and > it would be nice if there was some easy way to identify and print just > the first-needed sections from Microsoft, because that's what people > will be trying to do with it. (Think about it: col -b is absurd) RTF is about as MS friendly as it can get. The final output formats for the Handbook(s) will be Plain text (7 bit ASCII) RTF, RTF95 (RTF95 is optimised for Word95, RTF for Word97) HTML TeX PostScript (from TeX) PDF (from TeX) Anyway, that's enough for the time being. As always, comments solicited. The new chapter layout is attached to this message, available from N