[issue27050] Demote run() below the high level APIs in subprocess docs

[R. David Murray]

R. David Murray added the comment:

Just as a data point, I always found it confusing when viewing the subprocess docs that I had to page past the 'convenience functions' to get to what I consider to be the "real" docs, the docs for Popen.  I rarely use the convenience functions; I find it harder to remember how they work than just using Popen, and in any case I usually end up writing an application-specific 'cmd' function that uses Popen.  I haven't tried using run yet, so I don't really have an opinion on that.

I suppose its like carrying a swiss army knife in your pocket rather than carrying a steak knife, a pair of scissors, and a screwdriver.
If you were carrying a toolbox with *all* the tools, it might be different, but your choices are three tools or the swiss army knife, and to make matters worse those individual tools are really just the swiss army knife in disguise, but it looks different enough to be confusing.

Maybe having table of links at the start of the doc would be the most helpful, regardless of how the docs are re-organized.

----------
nosy: +r.david.murray

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue27050>
_______________________________________