Date: Mon, 8 Jan 1996 18:47:38 +0100 (MET) From: grog@lemis.de (Greg Lehey) To: jkh@time.cdrom.com (Jordan K. Hubbard) Cc: doc@FreeBSD.org Subject: Re: How do folks feel about legitimizing the `style split' in our docs? Message-ID: <199601081747.SAA00295@allegro.lemis.de> In-Reply-To: <21952.821079051@time.cdrom.com> from "Jordan K. Hubbard" at Jan 7, 96 09:30:51 pm
next in thread | previous in thread | raw e-mail | index | archive | help
Jordan K. Hubbard writes:
>
> (sorry, I was too lazy to copy the original message, but...)
This is a thing that I've done a lot of soul-searching about. I agree
with Jordan's original concerns, so much that I wouldn't be able to
get a really good assessment in in time to be of use to anybody, so
I'll give you a rough assessment. Basically, yes, we need both
approaches. We probably need a larger number than 2.
>> 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).
>
> Well, I still don't see that as grounds for a "split" so much as a
> "beginner's section." I agree that the new users definitely need
> a blinking neon arrow pointing at *some* section of the handbook.
Pointers are devices which don't get enough use in books. I had a big
fight with O'Reilly about my porting book, and lost. The result is a
great loss to the book: I have lots of references in there, and
instead of pointing to a page ("See Chapter 15, Signals, page 247"
becomes "See Chapter 15, Signals, the section entitled "BSD signal
handlers"). The result is that you either have to sequentially search
the chapter (once you have found it, not the easiest thing in itself),
or you go indirectly via the table of contents, also an inconvenience.
In the "Installing FreeBSD" book (latest version, as of yesterday, is
on freefall.FreeBSD.org:/incoming/shortbook.tar.gz, *please* review it
and complain about everything except the appalling pagination), I have
had even more of a problem. Take a look at Appendix A to see a
possible way of handling the questions "To install FreeBSD you do
if (installing_alone)
{
if (EIDE)
lose ();
if (ATAPI)
maybe_lose ();
if (sharing_disk)
{
if (MicroSoft ())
lose_lose_lose ();
if (disk_already_contains_data ())
{
FIPS ();
maybe_win ();
}
}
switch (media)
{
case CDROM:
win ();
case TAPE:
maybe_lose ();
case FLOPPY:
mega_lose ();
...
Well, you get the message. There are too many branches, and the
result is that it's difficult to read. I've done what I can, but
basically Appendix A really does try to call functions like this.
All this verbosity leads in to:
>> Second, some chapters are difficult to split in this way. Take "my"
>> chapter, on Kernel Configuration (btw, John, I reread that for the first
>
> OK, so I see that the paradigm breaks down for a few sections.
> Perhaps that simply points to the need for a (gag-inducing word coming
> up) meta-paradigm! :-) In english, what I'm saying is that perhaps we
> should extend the concept of howto/expert level documentation up one
> level then so that the novice users never even *see* your Kernel
> configuration document unless they follow a link that leads them over
> to the `How it works' section material.
Maybe you could think of a simpler word :-)
> I mean, we've got this fancy SGML thingie, can't we make several
> `virtual documents' from the same source material? Why should we
> confine ourselves to one "top level representation" of The Handbook?
This is the point. I'm not really happy with the way you navigate
through HTML documents anyway (maybe I just don't understand them),
but it should be possible to define several different ways to follow
through, depending on what you want to do. I think a bit of
brainstorming could come up with some useful innovation in this area.
Greg
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199601081747.SAA00295>