[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: FAQ bug
From: |
Andries . Brouwer |
Subject: |
Re: FAQ bug |
Date: |
Mon, 11 Feb 2002 17:19:53 GMT |
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