Re: FAQ bug

[Andries . Brouwer]

> I just want to know how to make things better.

I tried to explain. Maybe the ideas are so new that I must
be more explicit. Let me try.

People do not read documentation for pleasure.
For pleasure maybe they read a novel.
Documentation is a necessary evil.
The saying goes: "when all else fails, read the docs".

Good documentation makes it easy for the user to find
what he is looking for.

A 1000-page book that contains everything, is not
what the user needs. He has a job to do, and part of
this job is to make some program work, and the fewer
seconds spent on that, the better.


Now about grub. Imagine that you are talking to an expert,
who knows all about computers, even all about boot loaders,
but nothing about grub.

Can you tell this expert in ten lines what grub does?
Can these ten lines be the first ten lines in the introduction?
Can these ten lines be the first ten lines in the man page?

How does a boot loader work? One has a setting-up phase.
There are files that transport information from the
setting-up phase to the time of booting. There is a boot loader.

Explain these things. In very few words.

Today, if I read grub(8), this man page assumes that the reader
already knows the big picture, how grub is set up. It starts
talking about the grub shell. Is that the program that does the
setup? Or is that the program that runs at boot time? Nobody
knows, it is not in the man page. The author of that man page
was not thinking of the reader.

Today, if I read "info grub" the very first thing I need is
the big picture. But I cannot find it. There are words, lots
of words, but they were not written with the user in mind.
They were written by an implementer who likes to talk a lot
about this beautiful program he has written.

Do you understand?

Andries