Date: Sun, 7 Jan 1996 21:17:28 -0800 (PST) From: Jake Hamby <jehamby@lightside.com> To: "Jordan K. Hubbard" <jkh@time.cdrom.com> Cc: doc@freebsd.org Subject: Re: How do folks feel about legitimizing the `style split' in our docs? Message-ID: <Pine.BSF.3.91.960107210942.275C-100000@localhost> In-Reply-To: <21683.821075998@time.cdrom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
------------------------------------------------------------------------------
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.3.91.960107210942.275C-100000>