Do you feel bad because of the Python docs?

[Devin Jeanpierre]

On Tue, Feb 26, 2013 at 11:38 AM, Adam W. <AWasilenko at gmail.com> wrote:
> I think learning a language from the documentation is an unreasonable expectation and burden for the authors.

That's how I learned it. The Python tutorial, together with the stdlib
reference manual, are often recommended to beginners to Python in
order to learn it. The combination of the documentation and consulting
other programmers helped me learn the language just fine.

> Buy a book, take a class, they are designed to provide you with a path from start to finish in a sensible manner, the documentation in my opinion is supposed to be a reference and a refresher with an assumed level of basic fundamentals.

I would assert it isn't very kind to those even with basic fundamentals.

For example, under precisely what circumstances does int() raise
TypeError? You won't find that under either int's documentation, or
TypeError's documentation, you have to look it up under __int__, which
is _not_ a basic fundamental. And rather than helping you along the
way, the documentation for int() actively misleads you by its
implicature that the only acceptable types are strings, ints, and
floats. And then even if you have the foresight to remember "oh yeah,
isn't there a special method for this?", you have to find the
documentation for __int__, which is itself is three quarters of the
way down this massive page:
http://docs.python.org/2/reference/datamodel.html .

-- Devin