Bitching about the documentation...

[BartlebyScrivener]

>>The solution is clear: the distro maintainers should require that all
code contributions must come with good docs.  When a code submission
comes in, the distro maintainers should critically review the
accompanying docs, note any shortcomings and constructively ask for
improvements from the contributor until the docs are good.  <<

Well, that might be asking a bit too much of the programmers, who
perhaps don't exactly enjoy mucking about in the lowlands of English
grammar and syntax. All I was saying is you should court writers and
mid-level programmers with writing skills (not saying I'M mid-level,
I'm still learning) to HELP with creating good documentation. When a
writer thinks about helping they go to a page where they are greeted by
a bug report menu or CSV notices or some such. That's why most of your
really good stuff for beginners is on separately created web pages,
where writers simply take matters into their own hands. Also fine, not
saying it should be different.

Again, taking something like Bengt Richter's suggestion as just one
example. To me the module docs are almost incomprehensible without good
examples. Why not have a button where people could submit nice SHORT
examples illustrating otherwise pure theoretical code and geek-speak.
Of course, the editors would decide in a survival-of-the-fittest
contest which example gets used, but the point is you'd get good free
examples this way.

In general, I'd be happy to help a programmer with writing if it meant
I would learn programming along the way. It should be that easy. 

rd