[Python-ideas] Adding `pathlib.Path` method that would send file to recycle bin

[Andrew Barnert]

On Jan 5, 2015, at 2:41, Ethan Furman <ethan at stoneleaf.us> wrote:

> On 01/04/2015 05:13 PM, Steven D'Aprano wrote:
> 
>> Although the quality of contributions is variable, the PHP community has 
>> made a very interesting decision to integrate community-supplied 
>> information with official docs:
>> 
>> http://php.net/manual/en/function.dechex.php
>> 
>> I wonder how we might do something similar?
> 
> I hope that we do not.  A separate wiki is fine, but the official docs should just have the official stuff in them.

MSDN has something similar. They've gone back and forth between a half-dozen different models, and I think at present it's just (formatted) comments on each documentation page. At any rate, it's very clear what's official documentation and what's some guy saying "the docs say you can't do Foo, but here's some code that simulates Foo in most cases". 

I've found useful stuff there. Then again, I've also found live code (and StackOverflow questions, etc.) that's broken because someone took some sample fragment from a comment and used it inappropriately (often ignoring the very next comment that explains why you shouldn't do that if X, Y, or Z).

Both PHP and MSDN have a separate page for each function/method/attribute, while Python has a page per module (broken down into sections that are usually very nicely organized, so I wouldn't want to lose that...), so I'm not sure a similar comment format would work in the first place.

Maybe allowing inline comments at every section break, entry, or even paragraph would work (like the way PyGame docs have inline example-search and other links)? But that could easily lead to docs that are so cluttered with comments (or with disclosure triangles, if they start off hidden) that the actual documentation is hard to read.

> If the docs were a wiki, we'd have scads of entries on "how to program <language-x> in Python",

In other fora (python-list, python-tutor, StackOverflow, comments on widely-followed blogs, etc.) when someone suggests writing Java-style code instead of Pythonic code they usually get quickly shouted down, often even with good explanations, so I'm not sure things would be any worse on a wiki attached to the Python docs. Also, the Python wiki is already a wiki, and isn't dominated by that kind of cruft. So I'm not sure that problem is as much of a threat.

That being said, I agree with your conclusion. Docs seem to work best information that's managed like code; things that aren't quite docs but are useful may work best in other ways, but people have already found the wiki, StackOverflow, ActiveState, blogs, etc. and aren't having any problem using them. And, of all the alternate places to find elaborated documentation, the wiki seems to be among the least popular, which doesn't seem to imply that more wikification is the answer to any relevant question.