[Python-Dev] Distribution tools: What I would like to see

[Mike Orr]

On 11/26/06, Phillip J. Eby <pje at telecommunity.com> wrote:
> I have noticed, however, that a signficant number of help requests for
> setuptools can be answered by internal links to one of its manuals -- and
> when a topic comes up that isn't in the manual, I usually add it.

Hmm, I may have a couple topics for you after I check my notes.

> The "diff" issue is certainly there, of course, as is the fact that there
> are multiple manuals.  However, I don't think the answer is fewer manuals,
> in fact it's likely to be having *more*.  What exists right now is a
> developer's guide and reference for setuptools, a reference for the
> pkg_resources API, and an all-purpose handbook for easy_install.  Each of
> these could use beginner's introductions or tutorials that are deliberately
> short on details, but which provide links to the relevant sections of the
> comprehensive manuals.

I could see a comprehensive manual running forty pages, and most
readers only caring about a small fraction of it.  So you have a
point.  Maybe more impotant than one book is having "one place to go",
a TOC of articles that are all independent yet written to complement
each other.

But Talin's point is still valid.  Users have questions like, "How do
I structure my package so it takes advantage of all the gee-whiz
cheeseshop features?  Where do I put my tests?  Should I use unittest,
py.test, or nose?  How will users see my README and my docs if they
easy_install my package?  What are all those files in the EGG-INFO
directory?  What's that word 'distribution' in some of the function
signatures? How do I use entry points, they look pretty complicated?"
Some of these questions are multi-tool or are outside the scope of
setuptools; some span both the Peak docs and the Python docs.  People
need an answer that starts with their question, rather than an answer
that's a section in a manual describing a particular tool.

-- 
Mike Orr <sluggoster at gmail.com>