Date: Fri, 30 Oct 1998 13:16:09 -0700 From: Sean Kelly <kelly@plutotech.com> To: Nik Clayton <nik@nothing-going-on.demon.co.uk> Cc: doc@FreeBSD.ORG Subject: Re: RFC: Handbook reorganisation Message-ID: <363A1E89.DFEC36A0@plutotech.com> References: <19981029221106.19143@nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
> What follows is my collected thoughts after staring hard at the Handbook > for the past seven months. I think it's reasonably widely acknowledged that > the Handbook could use some reorganisation (and, eventually, tighter > editing), and this is how I'm (currently) thinking of doing it. Agreed. When I wrote documentation professionally (for a certain evil empire), full-time editors were employed who met regularly to discuss overall tone and direction, and who meticulously pored over every page to ensure consistency. The end result was still not very useful, but it sounded coherent. :-) > The layout that I'm proposing will look something like this > <URL:http://www.freebsd.org/~nik/hb/new-layout.txt>; Commenting on the new organization would be easier if we were to make a statement about what the intended goal and audience is: should the handbook be targeted to the lowest, most computer-unaware user possible, or is some familiarity with Unix assumed (for example)? This should be stated in the handbook itself, in the front matter. In fact, the section "Unix Basics" might be expanded, or removed altogether once that's nailed down. And we can start evening out the tone as well: I wrote the "Printing" chapter to a fairly inexperienced but Unix-aware user; other chapters assume more confidence and experience; the tone changes from chapter to chapter as a result. > Rename to "Configuring FreeBSD". This part will talk about how you > configure FreeBSD and *most* of the applications that come with it. With material that tells how to edit /etc/rc.conf, for example? Would "How to customize the console" or "Turning on process accounting" be in here? > This should not (IMHO) include things like Sendmail or Printing. > Sendmail is really part of the wider application set, and Printing > deserves a part to itself. Aww, shucks! (But then again, I guess printing is a pretty bloated topic :-) > Create an overview section that discusses the sort of configuration > knobs that can be tweaked with a FreeBSD installation, and an explanation > of where to find out how to tweak those things. OK, sounds good. > Break the FreeBSD configuration process into "While the system is > starting", "While the system is running", and "Configuring the FreeBSD > kernel". It might serve the user better to make these sections tell what's configurable, rather than when. I like to think I'm experienced with Unix, but I'm having a hard time differentiating between things to configure during startup versus those after it's running. I might have my laptop's network set up for my home network (startup), but on those odd days I bring it to work, I run ifconfig to get it talking there (while running). What are some topics you would put into each of these two sections? > Document how to configure the kernel (done) and how to tweak the > boot/run time options (/etc/rc.*, sysctl and so on). Good. > Keep disk quotas in this part. OK. > Move Security out of this part, into both the Applications and Networking > parts. The IPFW discussion belongs in "Internet Communications" and the > Kerberos and S/Key discussions in "Applications". OK. > Part 3: Printing > > Based heavily on the existing Printing chapter, and only slightly > reorganised; OK. > Start with an overview chapter. Good. > Then have a "Hardware setup" chapter. This is independent of which > particular spooler you're using. Yes, true. Good idea. > Then a chapter that talks about LPD. This will consist of most of the > existing Printing chapter. OK. > Placeholder chapters to talk about printing use LPNG and other > alternatives. Out of curiosity, how widespread is LPNG? I installed PLP (its predecessor) at a site I used to administrate, and when I came to Pluto, I found LPRNG here. But I don't run it at home. > Placeholder chapters to talk about Network printing. This may or may > not be necessary, depending on how generic the information about the > LPD spooler is. I'm thinking in particular of things like "Printing to a > Windows NT printer" which isn't covered. A good idea, which Jim Dutton recommended as well. If there's time (and writers with experience, such as Jim), there should be printing in the reverse direction as well (Windows client to Unix server). > Part 4: Network Communications > ... > Perhaps "Before using a modem with FreeBSD" is a better title? Or just "Using a Modem with FreeBSD". Even with the title "Serial Communications" for this part, there should be (on the part's introduction) text that tells people who think they're clever and say, ``Ah, the `S' of SLIP is Serial, so to set up my SLIP connection, I should read this part,'' that they'll find SLIP and PPP setup in the next part. > Part 5: Internet Communication > > Create an "Internet Communication" part. Explain the basics of > communicating over the Internet (IP address, gateways, routing, > netmasks, ports). "PPP and SLIP" become two distinct chapters under this > part. Both refer back to the "Before using a modem with FreeBSD" chapter. Excellent. > This is not quite right -- logically, information about SAMBA should > sit in here as well. And have mention back in the printing section. > ... Or perhaps a couple of chapters, one called > "Networking with Windows" and one called "Networking with Macs" or > similar? But then that's not really a part of "Internet Communications" > which is what this part is about. Perhaps. But all of that could go under a larger heading of "Networking," with chapters that explain that TCP/IP is the primary (sole?) networking supported by FreeBSD (part of the Internet Overview), setting up communications with TCP/IP (PPP, SLIP, Ethernet), and applications using TCP/IP (SMTP, NFS, NIS, NTP, Networking with Windows, Networking with Macs), and Security. What do you think? > Should definitely include Quake and Doom :-) Yes! > Part 7: Advanced topics > ... All good. > Part 8: Contributing to FreeBSD OK! (Boy, this is getting long! :-) > Part 9: Appendices > ... Good. > Obtaining FreeBSD should probably move into Part 1, immediately before > "Installing FreeBSD". Absolutely. Whew! You've certainly put a lot of thought into this. Well done! I'm passionate about documentation myself, but I wish I could find the time to do it. How do you do it? > The more I look at this, the more I think that calling the Handbook a single > DocBook 'book' is a mistake. Having it as a 'set' (which can contain > multiple books) would be more useful. Uh oh. > By doing this, everything moves up one level in the hierarchy. All the > <part>s listed above become <book>s, <chapter>s become <part>s and so on. > I think this makes more sense, as the documentation for FreeBSD becomes > a set of books. A book that introduces FreeBSD, a book that talks about > using modems with FreeBSD, a book that talks about Networking (one part > would deal with TCP/IP and the Internet, one part with Windows, one part > with Macs, and so on). Perhaps, but is there really going to be enough material to justify an entire book on introducing FreeBSD? An entire book on modems? I concede that Unix can be exceedingly complex, but using "book" terminology within the set (``For more information on Printing, see the book `Printing' '') might be off-putting, especially to novice users who'd grow trepidatious at the realization that they'd have to read entire book just to get the printer set up. 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. Anyway, I've been itching to do some more writing (if work permits, of course). Let me know what I can start working on. --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?363A1E89.DFEC36A0>