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

[Carl Banks]

On Aug 11, 3:08 pm, Paul Boddie <p... at boddie.org.uk> wrote:
> Certainly, the documentation situation with
> Python is not ideal; otherwise, people would not be complaining about
> it so frequently.

I will not take an opinion on whether Python's documentation is ideal
(more on why below) but I will opine that the conclusion doesn't
follow from your premise.  People's expectations of what documentation
should be are too different, there will always be people who aren't
pleased.  IOW, there is no "ideal".

For example, kj (who started this mess of thread) complained that
pydoc didn't give exhaustive usage documentation.  In contrast, I
think pydoc gives too much information.  I would rather have only the
bare minimum; I don't want to pan through ten paragraphs just to see
what the fifth argument is.

So who's right?

No one, there is no "right".  Unfortunately some people can't or won't
respect that opinions differ; they have to take perceived defects in
the docs personally.


Carl Banks