Date: Sun, 7 Apr 2002 11:35:39 +0200 From: Szilveszter Adam <sziszi@bsd.hu> To: freebsd-doc@freebsd.org Subject: Re: Splitting the Handbook? (was: [a couple of new doc PRs]) Message-ID: <20020407093538.GB539@fonix.adamsfamily.xx> In-Reply-To: <20020406221709.GA1181@hades.hell.gr> References: <20020404062954.6607E2E827@mail.freebsdmall.com> <20020406221709.GA1181@hades.hell.gr>
next in thread | previous in thread | raw e-mail | index | archive | help
Hello everybody, I am getting a bit late into this discussion, but I have a great excuse: I have been sleeping:-) So. I think that splitting up the Handbook would be a good idea. It is getting too large in every respect. (To read, to process, to search, to...:-) Also, a division into a "user's" and "admin's" part seems like a good idea. (On the assumption that the Developers Handbook continues to evolve so as to offer information to those who wish to use FreeBSD as a development platform.) However, I think that before starting wholesale reorganizing the stuff, we should have a clear set of requirements towards the Handbook. What do we want the Handbook to be? During the previous reorg run (in the runup to the 2nd Edition) this requirement was that it had to become more of a print title, with better-looking book output, consistent grammar and style, index, front and backmatter etc. Now, we have to decide what the Handbook (or the books that will make up the series replacing it) will try to cover. First. I think that we should not try to blur the line between users and admins by including admin tasks in the user volume. My reasons: - It is already causing waaay to much trouble when people seriously believe that just because a normal office worker (or home user for that matter) was able to "admin" a Win95/98/ME box all by himself (with sometimes stunning results, see viruses, security patches not applied, chaos because of many installed shareware items etc) they will be able to do same for a UNIX-type system. Or that they should. In my opinion, UNIX-type systems require a real admin or they are worse than your Win 9x box. Especially when they are on a network. This is why when someone asks me if they should consider using ... (subsitute Linux or whatever here) in the office I will be asking them (among others): Will there be some person who will be able to administer the boxen? And this is why I think that UNIX-type OSen will never make it big on a common PC in the home. (Appliances are another matter) - Because admin tasks usually require root. (Case in point: You may be able to to compile packages as a user, in fact I do this all the time, but not install them normally, because at least the pkg database management will require root.) If you have root on a machine, then you are an admin no matter if you at the moment work under a user account (as indeed you should.) In fact, I consider that admins should have at least a non-wheel user account as well because doing certain tasks like browsing, email etc may pose even less risk that way: there are just less system files that a non-wheel user can read, for ex.) So, the User's Guide should be something like the USD used to be way back when: orientated towards users, no more. Of course, I do not think we should waste time describing the stunning games in the base system any more, but you get the idea. The aim of the User's Guide is to help me get work done when I login to a FreeBSD system (possibly remotely) as one of the several users of the system and eg want to read my email, edit my homepage, or write my thesis with LaTeX. (All of which I have done on this system). The Admin's Guide, on the other hand, should be oriented towards admins who are already supposed to know their way around as users, but need to do different job: They may not care at all about X or photo editing or indeed thesis-writing, they need to maintain the system. For this, they need info on kernel recompiles, staying up-to-date, patching for security, staying with the -RELEASE branch if need be, coordinated installworlds from NFS-mounted /usr/obj, diskless systems, scripted installs, cloning possibilities, using hot-swap system components on SCSI and also on ATA, networking, VLANs, etc. Some of this info is at present missing, some in the Handbook and some in the Developers Handbook or elsewhere. And also, there should be a book for programming on FreeBSD, of course, not just for system hackers, but application programmers. Second. We should decide to what extent we want to include third-party packages into the series. Of course, the fact that FreeBSD is more than a kernel(TM) does not make our job easier. Yet, I think that if we start covering eg every major MTA just because not everyone loves sendmail, we will be before long writing a book about Internet Mail which just happens to use FreeBSD as its examples, not a FreeBSD sysadmin book. This would be needless duplication of effort with the documentation of these software packages (it really does not need a book to tell you that, contrary to the defaults, the startup file is installed under /usr/local/etc/rc.d on FreeBSD if you use the ports, but everything else works as described in the vendor docs, eg) and with some fine books from eg O'Reilly that already cover these and more. So I think the series should concentrate on the parts that are FreeBSD specific and make reference to the vendor docs (or even other literature) when appropriate. These are really just my 1st thoughts on the subject, feel free to take them and use them as you see fit, but I think that a similar set of requirements should be drawn up before we go ballistic with slicing up the content. -- Regards: Szilveszter ADAM Szombathely Hungary 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?20020407093538.GB539>