From owner-freebsd-doc Sun Jan 7 21:17:32 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.3/8.7.3) id VAA13362 for doc-outgoing; Sun, 7 Jan 1996 21:17:32 -0800 (PST) Received: from localhost.lightside.com (user58.lightside.com [198.81.209.58]) by freefall.freebsd.org (8.7.3/8.7.3) with SMTP id VAA13357 for ; Sun, 7 Jan 1996 21:17:29 -0800 (PST) Received: (from jehamby@localhost) by localhost.lightside.com (8.6.12/8.6.9) id VAA00391; Sun, 7 Jan 1996 21:17:52 -0800 Date: Sun, 7 Jan 1996 21:17:28 -0800 (PST) From: Jake Hamby X-Sender: jehamby@localhost To: "Jordan K. Hubbard" cc: doc@freebsd.org Subject: Re: How do folks feel about legitimizing the `style split' in our docs? In-Reply-To: <21683.821075998@time.cdrom.com> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org Precedence: bulk On Sun, 7 Jan 1996, Jordan K. Hubbard wrote: > "What the hell is he talking about?" they ask. > > I'm talking about our long-standing problem with having docs submitted > in one of two fairly different styles: > > 1 "How to do this ..." > > 2 "How this work works ..." > > [deletia...] > > Comments? John, would something like this conflict significantly with > your proposed reorg? Sounds like a good idea. I have two comments, though: First, I think that the Handbook SHOULD be split in the sense that the first section NEEDS to be focused for new users (assuming a mixture of readership between people new to Unix and experienced Unix admins new to FreeBSD). It needs to cover: 1) Which hardware is adequate/recommended to run FreeBSD on, 2) How to install it without clobbering your precious DOS partition, 3) How to perform basic sysadmin tasks and/or what books to read (we have the advantage over Linux in that we can say, "Just read this book and follow the SunOS/BSDI instructions," rather than "Linux is weird in almost every way, so buy a Linux-specific book or you'll be hopelessly confused"). :-) Second, some chapters are difficult to split in this way. Take "my" chapter, on Kernel Configuration (btw, John, I reread that for the first time in a few months, and I should do a bit of work on it, I'll post some diffs soon), anyway, rebuilding the kernel is something that every competent sysadmin should do, on the other hand the "how it works" is VERY intertwined with "how to do it." I doubt that anyone can "reorg" that chapter differently from how John and I settled on the layout, without making it less sensible than it is currently... So there is no hard and fast rule that will apply to every chapter. ------------------------------------------------------------------------------ Jake Hamby | E-Mail: jehamby@lightside.com Student, Cal Poly University, Pomona | System Administrator, JPL ------------------------------------------------------------------------------