[Python-ideas] docs.python.org: Short URLs

[Andrew Barnert]

On Feb 17, 2014, at 10:01, Andrew Barnert <abarnert at yahoo.com> wrote:

> On Feb 17, 2014, at 9:32, Ryan Hiebert <ryan at ryanhiebert.com> wrote:
> 
>> On Mon, Feb 17, 2014 at 11:25 AM,  <random832 at fastmail.us> wrote:
>>> 
>>> 
>>> I don't know why they should be redirects, no. I think what's being
>>> proposed in the article _was_ a separate page for every class and every
>>> function. PHP does that. .NET does that. Why shouldn't Python? Is it
>>> possible that the Python documentation suffers from excessive
>>> conciseness _because_ everything's on one page?
>> 
>> I don't know that it's necessarily because everything is on one page, but I could imagine that it's a contributing factor to why things are concise, and I could see that splitting things up into more pages would encourage longer prose and more examples. Longer isn't always better, but sometimes saying things multiple ways can help the message get across.
> 
> I think the conciseness and single-page-ness is often a virtue. It leads to people discovering other methods of the class whose method they're looking up.
> 
> For example, last week there was a question on StackOverflow from a novice who discovered str.partition because he was trying to figure out how to make str.split always return 2 elements and saw it on the same page. (He wanted to know how to make partition split N times instead of 1, and got a fancy genexpr as an answer that he could never have written himself and probably didn't understand, but that's a deficiency of SO, not of the docs.)
> 
> It's possible to design documentation that's the best of both worlds, using a hierarchical nav bar on the left, or even having the str.split page actually be a collapsible version of the str page with various sections pre-collapsed. And if someone is willing to do all the work for _that_, I have no issue. It's only if we're comparing current Python docs vs. PHP style "every function, even the most trivial, is entirely independent" docs.

That being said, there might be a good middle ground--a page that had just the docs on str, rather than on all builtin types, might be handy. But other than that one page on all of the builtin types, I can't think of any others that are overly large...
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20140217/2196bb53/attachment.html>