Richard Jones' Log: Please describe your Python packages!
This is getting frustrating. I subscribe to the PyPI RSS feed and far too often entries posted contain no description or they have something equally useless like "A wrapper for Shrubbery". What the hell is a "Shrubbery" and why should I care?
The second frustration is when a package has a somewhat useful short description "A package for doing spammish things" but there's no further information: there's no longer description, and the home page link points at the PyPI page itself. Nothing for the curious Python developer to get an idea of what the package does. Compare this with the Roundup Issue Tracker PyPI entry.
I have to ask in all seriousness why even bother uploading to the index if you can't be arsed to put in a description?
I could not agree more. This is one of the most critical points I wanted to blog about - the day I start a blog, that is.
PyPi should be to Python what CPAN is to Perl. But it currently lacks a level of Quality (should I say Kwalitee?).
Or is PyPi just an index hosted on the funds of PSF?
Should adding value (to current PyPi) be driven by the community as a separate stream/project?
This is a wider problem I've been experiencing lately. The commenter who says the description might be on the project page? Might be. Probably isn't! There are so many cheap and easy ways to "release" something these days that release is such a watered down term I've seen things "released" via pastebin. Seriously.
I've found the problem lately to be most pronounced in Django apps and jQuery plugins. It seems the bulk of small but useful little packages are released by an obscure blogpost or simple a dead-looking project page on google code. Description? I want documentation, or even a place for users to contribute it! I don't blame the authors. I hardly have time to release any little thing I do, and I know I wouldn't have time, so the answer is just to let the community do it.
I totally agree. I would be in favor of some type of review process.
The comparison with CPAN is appropriate, in that it shows that it is possible to do better.
Yep, a Python project pretty much doesn't exist until it has documentation. I think a long description isn't enough; it needs end user documentation otherwise I'm not going to bother with it. However, I have prematurely pushed packages to the index simply so I can start using a new package of mine in production without relying on a custom PyPI index.
But as a user I generally ignore these doc-less packages. What's worse though is that some people do not know how to write readable, easy-to-understand documentation.
Hi,
So people can use the software.
Sometimes pypi is just used for a download url, to be used with easy_install/buildout etc. In that case the description of the software might be written somewhere else... like on the projects webpage.
Maybe if there was a way for users to communicate with the package uploaders, then people could say 'wtf is this?' and other such stuff... Probably comments would help amazingly. Most other rss feeds, and project listing websites allow comments. That way more people can get, and react to feedback. Some projects live or die, based on user feedback - feedback might be the only thing motivating some people to work on stuff.
cu.