Social problems of Python doc [was Re: Python docs disappointing]

[Paul Rubin]

rurpy at yahoo.com writes:
> I took a look at the PHP docs last night which seem pretty well
> done.  The User Comments looked rather as I expected, there was
> useful info but most did not contain documentation quality writing.
> So if they are used as a source for improving the docs, there
> clearly must be a pretty large amount of editorial effort required,
> although much of it is probably just filtering out comments that
> don't provide any information appropriate for inclusion in the docs.

The comments section contains questions from users and answers to
those questions from other users.  What you may be missing is the part
of the comments useful to the doc maintainers is primarily the user
questions, rather than the user answers.  The questions show the doc
writer exactly what parts of the official doc are unclear or
incomplete.  The user-written answers may be wrong or generally crap,
but the doc writer now knows what to do to improve the doc.  That's
why it's such a win to have the comments on the same page as the
official docs.

See also the user-commented http://book.realworldhaskell.org/read/
where the comments really helped clarify the finished (dead tree) text.