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

[exarkun at twistedmatrix.com]

On 11 Aug, 11:37 pm, pavlovevidence at gmail.com wrote:
>
>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.

This is right on.  Excellent point, Carl.

Jean-Paul