OpenSource documentation problems

[Adriaan Renting]

Marked -1 Flamebait, but I'll respond anyway.

I've read the documents he refers to, and although I agree that the Python docs aren't perfect, I do not agree with him on which points. I for example do think it's important to incude info on which versions of the language support a feature.
He seems to think the GNU man pages are nice, but I find them very awkward as they have no hierarchical organization, and most miss examples.

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. The other part where a lot of OSS seems to be lacking is user interface design.

I think the cause is that the OSS movement is almost solely comprised of programmers, while in a commercial environment there will be a lot of documentation writers and interface designers (and marketing, etc...)
I know I write my own documentation for the code I create, but I know I'll not do as good a job as a separate good doc writer would. In general I think the programmers should not write the documentation, and should not be the sole designers of the UI either.

The good commercial docs are better because there it is understood how important this is. I myself have always liked the Borland documentation a lot.

The big question is: how to attract more doc writers to the OSS movement?

Adriaan Renting.