Re: [Python-ideas] docs.python.org: Short URLs
I did mean to take it to the list. Just replying so it is there content-wise. On 17 February 2014 15:49:16 CET, Chris Angelico <rosuav@gmail.com> wrote:
Not sure if you meant to mail me this privately rather than post on-list. I'll keep this private for now, but feel free to take it to the list.
On Tue, Feb 18, 2014 at 1:42 AM, Markus Unterwaditzer <markus@unterwaditzer.net> wrote:
On Tue, Feb 18, 2014 at 01:34:25AM +1100, Chris Angelico wrote:
I like the idea, but your URLs might conflict with other things.
I'd just display the other thing instead then. Actually i think this should be implemented in the 404 error handler or something like that.
That could be done, but I was thinking more of a safe way to type in a URL - maybe with a browser plugin, even - that can't possibly bring up the "wrong thing".
Would it be too awkward if namespaced?
http://docs.python.org/[ver]/kw/str
and then have a keyword index (hence "kw", which is nice and short) which could have function/class names, common search keywords, a few aliases (regex -> re), etc, etc.
We can have that too, additionally. /name/ would strike me as more obvious, though this is just a matter of preference.
Either way. "kw" was the best thing I could come up with at short notice. My point is to namespace it; what the name actually is can always be bikeshedded :)
ChrisA
On Mon, Feb 17, 2014 at 03:51:58PM +0100, Markus Unterwaditzer <markus@unterwaditzer.net> wrote:
Either way. "kw" was the best thing I could come up with at short notice. My point is to namespace it; what the name actually is can always be bikeshedded :)
Painting it 'term'. Oleg. -- Oleg Broytman http://phdru.name/ phd@phdru.name Programmers don't die, they just GOSUB without RETURN.
I'm not sure that just these URLs are going to be any more helpful than what we currently have: ``http://docs.python.org/3.2/library/functions.html#str`` Are we looking at adding separate pages for each function, to give more in-depth details to function, or is it really just a redirect? Ryan On Mon, Feb 17, 2014 at 8:55 AM, Oleg Broytman <phd@phdru.name> wrote:
On Mon, Feb 17, 2014 at 03:51:58PM +0100, Markus Unterwaditzer < markus@unterwaditzer.net> wrote:
Either way. "kw" was the best thing I could come up with at short notice. My point is to namespace it; what the name actually is can always be bikeshedded :)
Painting it 'term'.
Oleg. -- Oleg Broytman http://phdru.name/ phd@phdru.name Programmers don't die, they just GOSUB without RETURN. _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
On Mon, Feb 17, 2014, at 10:24, Ryan Hiebert wrote:
I'm not sure that just these URLs are going to be any more helpful than what we currently have:
``http://docs.python.org/3.2/library/functions.html#str``
Are we looking at adding separate pages for each function, to give more in-depth details to function, or is it really just a redirect?
[bikeshedding intensifies] I, personally, if given a URL consisting of only "str", would expect it to lead to the documentation of the str _class_ (currently mostly at http://docs.python.org/3.2/library/stdtypes.html#string-methods), more or less
On Mon, Feb 17, 2014 at 10:17 AM, <random832@fastmail.us> wrote:
On Mon, Feb 17, 2014, at 10:24, Ryan Hiebert wrote:
I'm not sure that just these URLs are going to be any more helpful than what we currently have:
I, personally, if given a URL consisting of only "str", would expect it to lead to the documentation of the str _class_ (currently mostly at http://docs.python.org/3.2/library/stdtypes.html#string-methods), more or less
Yeah, that would be a better place to redirect for 'str'. I was just pointing that I'm not sure what these URLs really gain us, if they aren't meant to be used as the canonical URLs, since the #identified URLs are perfectly useful as permalinks. Does having these redirects make it easier to find these things using a search engine? If not, we gain some neat URLs that are still only useful to those of us that actually already know the documentation anyway.
On Mon, Feb 17, 2014, at 11:40, Ryan Hiebert wrote:
Yeah, that would be a better place to redirect for 'str'.
I was just pointing that I'm not sure what these URLs really gain us, if they aren't meant to be used as the canonical URLs, since the #identified URLs are perfectly useful as permalinks. Does having these redirects make it easier to find these things using a search engine? If not, we gain some neat URLs that are still only useful to those of us that actually already know the documentation anyway.
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?
On Mon, Feb 17, 2014 at 11:25 AM, <random832@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.
On Feb 17, 2014, at 9:32, Ryan Hiebert <ryan@ryanhiebert.com> wrote:
On Mon, Feb 17, 2014 at 11:25 AM, <random832@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.
On Feb 17, 2014, at 10:01, Andrew Barnert <abarnert@yahoo.com> wrote:
On Feb 17, 2014, at 9:32, Ryan Hiebert <ryan@ryanhiebert.com> wrote:
On Mon, Feb 17, 2014 at 11:25 AM, <random832@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...
On 18 Feb 2014 04:39, "Andrew Barnert" <abarnert@yahoo.com> wrote:
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... That's the main one, although some of the module docs jam a tutorial, reference and cookbook into one page, which can be a bit overwhelming. The trick lies in figuring out how to split it up without breaking any existing deep links. I actually wonder if there might be a benefit in having Sphinx generate a full "index" URL subtree, where each of those pages links back to the relevant anchors in the existing docs. That would be potentially useful in its own right (as a short hand for "here's all the places that provide info about str"), as well as potentially helping with SEO. Cheers, Nick.
_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
On Mon, Feb 17, 2014 at 12:25:03PM -0500, random832@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?
Because someone has to write all those pages. Do you want to lead the effort? Oleg. -- Oleg Broytman http://phdru.name/ phd@phdru.name Programmers don't die, they just GOSUB without RETURN.
On Mon, Feb 17, 2014 at 12:25:03PM -0500, random832@fastmail.us wrote:
On Mon, Feb 17, 2014, at 11:40, Ryan Hiebert wrote:
Yeah, that would be a better place to redirect for 'str'.
I was just pointing that I'm not sure what these URLs really gain us, if they aren't meant to be used as the canonical URLs, since the #identified URLs are perfectly useful as permalinks. Does having these redirects make it easier to find these things using a search engine? If not, we gain some neat URLs that are still only useful to those of us that actually already know the documentation anyway.
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? _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
I agree, it would be a better idea to have short and meaningful URLs, but as far as i know, this would require major modifications to Sphinx (unless you're actually creating an RST page for every object) and would require significantly more effort than the change i am suggesting. In my original mail i didn't even consider the SEO-aspect of short URLs, i just remembered from my PHP days that typing php.net/function_name was very helpful once i've discovered i can do that. -- Markus
On Mon, Feb 17, 2014 at 11:17:16AM -0500, random832@fastmail.us wrote:
On Mon, Feb 17, 2014, at 10:24, Ryan Hiebert wrote:
I'm not sure that just these URLs are going to be any more helpful than what we currently have:
``http://docs.python.org/3.2/library/functions.html#str``
Are we looking at adding separate pages for each function, to give more in-depth details to function, or is it really just a redirect?
[bikeshedding intensifies]
I, personally, if given a URL consisting of only "str", would expect it to lead to the documentation of the str _class_ (currently mostly at http://docs.python.org/3.2/library/stdtypes.html#string-methods), more or less _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
Sure, i agree. The script i posted meshed all dictionaries (one for functions, objects, classes, modules each) together in arbitrary order, i know this can be improved. -- Markus
participants (6)
-
Andrew Barnert -
Markus Unterwaditzer -
Nick Coghlan -
Oleg Broytman -
random832＠fastmail.us -
Ryan Hiebert