On 11/26/06, Phillip J. Eby <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
