Re: [Python-Dev] Distribution tools: What I would like to see
At 01:21 PM 11/26/2006 -0800, Mike Orr wrote:
A comprehensive third-party manual that integrates the documentation would be a good place to start. Even the outline of such a manual would be a good. That would give a common baseline of understanding for package users, package developers, and core developers.
A number of people have written quick-start or how-to guides for setuptools, although I haven't been keeping track.
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.
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.
My emphasis on the existing manuals was aimed at early adopters, who were likely to be familiar with at least some of distutils' hazards and difficulties, and thus would learn most quickly (and be most motivated) by seeing what was different. Obviously, nearly everybody in that camp has either already switched or decided they're not switching due to investment in other distutils-wrapping technologies and/or incompatible philosophies. So, the manuals are no longer adequate for the next wave of developers.
Anyway, I would be happy to link from the manuals and Cheeseshop page to quality tutorials that focus on one or more aspects of developing, packaging, or distributing Python projects using setuptools.
On 11/26/06, Phillip J. Eby pje@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 wrote:
On 11/26/06, Phillip J. Eby pje@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.
You said it way better than I did - I feel totally validated now :)
-- Talin
participants (3)
-
Mike Orr -
Phillip J. Eby -
Talin