Hacker News Reader

Comment by jimbokun | Hacker News Reader

As a very occasional Python user, it was very informative for me to see that String is a Sequence type. That immediately tells me something very important about Python, that I might be able to use similar functions and methods on lists, tuples, etc.

It's this comprehensiveness of the documentation that has impressed me before when I've needed to look things up about Python, and was enlightened about things I didn't expect to be.

View on HN

I agree that all of that needs to be made clear in the documentation, but that need doesn't directly entail everything being on one page. What if the string page noted at the top that was inherited from the sequence type, or displayed sequence's methods as well as string's methods, and noted that they there are from sequence?

That would work just as well, I think.

There's a bit of serendipity in a big page like that, where you can learn more than you expected. But it comes at the cost of distracting you from whatever it was you came to find.

If I remember that correctly, the 'one page' style of python documentation came only in rather recently (last couple of years, >2.3), and the previous style was split one many pages: http://docs.python.org/release/2.3.5/lib/module-string.html

Back then I always hoped for the single page, because I was beginning with the language and jumping up and down the toc table of the docu page to figure stuff out. For a beginner, having this possibility to switch from birds to frog perspective inside one page is really great. They could do a better job on integrating the page-internal toc navigation though.

Reply on news.ycombinator.com