OpenSource documentation problems

[Roel Schroeven]

Bryan Olson wrote:
> Adriaan Renting wrote:
> [...]
> 
>  > I do agree that a lot of OSS projects seem to lack somewhat in
>  > the documentation department, compared to a lot of commercial
>  > software. I would give the man page of gcc as an example, it's
>  > just one 6600 line blurb.
> 
> I don't see any need to look beyond Python for a good example of
> poor documentation.  Are there serious Python programmers who
> don't constantly struggle with errors and omissions in the doc?

There certainly are some areas where the documentation could be 
improved, but on the whole I think it's pretty good. I guess I'm not 
what you call a serious Python programmer, but still so far the 
documentation has provided answers to practically all questions I had.

> I don't mind the 6600 line blurb form, just so long as the info
> is there and is correct.

I agree. And on the whole I like manpages better than GNU's info system. 
info is good for providing background information and an overview of how 
everything works, but when I need a reference about command line options 
or config file settings, my experience is that I can find the needed 
information much easier in man pages.

-- 
If I have been able to see further, it was only because I stood
on the shoulders of giants.  -- Isaac Newton

Roel Schroeven