Re: FAQ bug

[Andries . Brouwer]

    From address@hidden Mon Feb 11 17:40:18 2002

    All I understand is that there is no way to make everybody happy. I
    devoted myself to the manual quite seriously, because the manual was
    very sparse, and many users complained that it was not friendly for
    newbies. So I prepended tutorials and an overview. And, now you
    complain that it isn't suitable for experts. *sigh*

More precisely, I complain that it is not suitable for anybody,
expert or newbie.

The purpose of documentation is to say everything as clearly as possible.
Sentences like "In the following chapters, you will learn how to ..."
are documentation errors. Every sentence must add information.

    As you know, what one knows already and what she wants to know are
    different (often dramatically) from person to person. So it is really
    difficult to determine what should be mentioned first of all and what
    should be said afterwards. I now realize that it may be wrong to put
    some sections (such as "History") in the chapter "Introduction", but
    what's wrong with others? The section "Overview" describes the "big
    picture".

Let me read "Overview" with you. The man page talks about the
GRUB command shell. Maybe I'll learn what that is.

> Briefly, a "boot loader" is ...

This is a good paragraph.

> GNU GRUB is a very powerful boot loader

This entire paragraph can be deleted without loss of information.

> One of the important features in GRUB is flexibility

This entire paragraph can be deleted without loss of information.

> Thus you can load the kernel just by specifying its file name ...

This is a good paragraph, but it assumes too much. It talks
about command-line interface before even mentioning to what
it interfaces. There is no big picture.

You know the picture too well, as the author of the program,
but the reader needs the global information first, before
the details come. And not advertising talk, but details that
are useful if one actually wants to use grub.

> In the following chapters, you will learn

This entire paragraph can be deleted without loss of information.

So, we achieved a reduction: five paragraphs have become two,
without any loss to either expert or newbie. But the second
paragraph is unreadable, and we need a paragraph in between.
"GRUB consists of programs and files. The programs ... are
used before rebooting, to set up information. The files ...
hold information. The program ... is used at boot time."
That is what I mean by the global picture.

After reading the overview, I have not yet learnt what this
grub shell is that the man page assumes I know about.

Andries