On Sat, 26 Nov 2005, Robbert Haarman wrote:
> The reason I wrote the HOWTO is that, in my opinion of course, the
> manpages don't make it clear how to set things up. Searching the
> archives for more information came up with some contradictory messages,
> and some instances of people being misled by the way things worked and
> the way things were described in the manpages. My HOWTO is an effort to
> gather the relevant information in one place, and provide clear steps
> for getting things working. Replacing the HOWTO with links to the
> manpages is not an option, because, first of all, the manpages don't
> provide the information that the HOWTO does, and secondly, the manpages
> are already assumed to have been read, so linking to them again wouldn't
> add anything.
>
> I completely understand your position that documentation should provide
> the details people need to understand how things work. I agree with
> that. I would have provided this information if I had, myself, known how
> things work. However, I don't know this, and it seems the only way to
> find it out would be to read the source code of various parts of the
> kernel. Still, I figured I had learned enough to write a useful and
> helpful document that at least described how to get things running. You
> clearly think this is harmful; I think it might help some people.
It is much more helpfull if you describe what information you feel is
missing, unclear or incorrect in the man pages.
Getting things running on a certain setup does not mean your procedure
will work in another situation. That's the big danger of promoting
some notes on how you did something to something that is suggesting it
is the right way of doing things.
Man pages are the autorative documentation. If you find them lacking,
help us in making them better.
-Otto
