[Chicago] [python-advocacy] Marketing Python - An Idea Whose Time Has Come

[Atul Varma]

On 4/20/06, Michael Tobis <mtobis at gmail.com> wrote:
> yet another time-consuming suggestion:
>
> Make the docs more useful! (Yes it's nothing new, but it ought to be
> represented on the list.)
>
> Python is so powerful that coding is much easier than documentation!
> While this is a good problem to have that doesn't mean we shouldn't
> try to solve it.

This is at the root of what I don't like about a lot of Python
packages.  I've heard some Python people refer to good documentation
as being "newbie-friendly" or "marketing-friendly", but I think of it
as just being, well, humane.

When I'm looking at a lot of Python packages--especially the web
development ones--because of their sparse and often inconsistent
documentation, they feel like they're unfinished products that are
still works-in-progress.  They don't "just work"; doing anything
nontrivial with them almost always involves tripping over outdated
documentation or code, or running into empty pages of text with TODO's
on them saying "we need to write this!".

As I believe Chad mentioned at the last ChiPy meeting, Zope has been
changing its API around so much since its original release that making
a basic web application with it is now an intimidating exercise in
frustration.

Before a product can be marketed well, it actually has to be a great
product to begin with.  And that doesn't just mean that it has to be
bug-free, which is already the case with most Python web frameworks
I've seen.  What it means is that good documentation and simple APIs
are actually *prerequisites* to good marketing.  Open-source products
like FreeType with long-term reputations for great documentation and
API stability are certainly ready for prime-time marketing, but
poorly-documented products with volatile or confusing APIs--like most
of the Python web frameworks I've seen--aren't.

People like me aren't avoiding Python web development frameworks
because there's too many of them.  They're avoiding the frameworks
because all of them are actually really confusing in one way or
another.  That's why a lot of people end up rolling their own, because
doing that is a lot easier than wading through and dealing with any of
the other Python-based solutions they see.

- Atul