[Numpy-discussion] Re: NumPy Glossary Was:Matlab page on scipy wiki

[Joe H. <jh...@oo...>]

Look, people are making this into something it isn't, and hating that.
I'm the last person in the world to want rules and bureaucrazy!
However, to make the wiki accomplish our goals, we need to agree on
some basic standards of judgement that we apply to ourselves.  We did
agree on some goals after SciPy '04: we want Python to be the
environment of choice for EVERYONE to do numerical manipulation and
data display, and to get there we need to present ourselves well (see
the ASP roadmap, linked at the bottom of DevZone).  I'm going to lay
out my reasoning why a particular workflow will reach that goal.  The
idea is to take full advantage of the Wiki Way without having the
liabilities of the Wiki Way.  I'm sorry this is long.  I have three
proposals due Thursday and I don't have time to edit much.

Bill, your argument is that you want to see a work in progress,
something you and anyone else can just go and contribute to whenever
you see a need, and that benefits from others making contributions
continually.  That's great from the point of view of an experienced
user of array math (in Python or otherwise) who is used to and
interested in contributing in the Wiki Way.  I'm sure most list
members, even of the scipy-user list, are still in this category.

It is therefore crucial for all of us to remember that such people are
*not* the main viewers of the site, at least not in the future we said
we hoped for, and probably not even now.  Most viewers are
dyed-in-the-wool users and potential users.  They want to see a clean,
professional, straightforward site with the simple life laid out
before them: bulletproof, current, binary installs for all their
preferred platform(s); readable, grammatical, complete, current,
well-assembled documentation for beginners and experts, both tutorial
and reference; examples, screenshots, demos; lots of good, indexed,
well-documented, shared software; and an active community.  "Under
construction" is an annoyance at best, and a deal-killer to many.
They may contribute someday, but that's not in their minds yet.

Recall that we have in our vision not just practicing scientists, but
also secondary-school students and their teachers, students taking
their only math or science course in college (under direction from
their professors and TAs), and even photographers and others who would
have need of the manipulations NumPy allows without necessarily
understanding them.  Our failure to gather a large following to date
is largely due to our not (yet) delivering on the site/project vision
above.  The reunification that is NumPy allows us to change that.
There are a LOT of people lurking, waiting for things to clean up and
professionalize.  Once they jump in, they'll tell their peers, who
have never heard of us, and so on.  The pure Wiki Way will never
produce the site that will start this hoped-for avalanche of ordinary
users.  Wikis are always under construction, always bleeding-edge,
always overdone in areas where their developers have interest, and
always weak in crucial places where they don't.

That said, wikis are *great* incubators.  Wikis get individual
subprojects completed fast and well by breaking down the barriers to
contribution and review.  DevZone tries to take advantage of the Wiki
Way while still producing a polished site.

The point of DevZone is twofold: first, focus contributors looking for
a project on the things that most need help: our weak spots, like
documentation.  I'm getting about an email a week from new people
looking to help.  This wasn't the case a month ago or before; it was
more like 1-2 a year.  Second, isolate the worst of "under
constructon" from the general view, so we don't look like a pile of
stubs, go-nowhere links, and abandonned or outdated projects.  The
second item probably makes more sense for larger projects (a user's
guide, etc.) than for pages like the glossary.  The model for workflow
is that projects are announced to the lists and immediately started in
DevZone.  When they reach a basic level of completeness and
cleanliness, something like a 1.0 release, they get a link from the
main site.  When they are no longer in need of new helpers or when
their development curve levels off, the DevZone link goes away.

Right now, it's pretty loose when to put the link in from the main
site to a project's page.  Anyone can do it.  To avoid a Wiki War, we
need to have some common vision for how much of a construction zone we
want the main site to be.

The development model I'm discussing is a little like the Plone model,
except that there is no elite administrator who decides when things
move up to the main site.  We dumped Plone for performance reasons,
and because the administrators were too busy with their Enthought work
to have time to do much on the site.  But, the basic Plone idea of
internal incubation is a good one.  In my ideal world, a group
(potentially including everyone, at least to a small degree) would
write a (large) doc and periodically ask the list to take a look and
comment.  At some point, they'd ask for objections to putting it on
the main site.  They'd try to satisfy any objections, and then put it
up.  I'd trust the authors of a smaller doc (that therefore was both
easier to write and had more people willing to give a quick review) to
make the decision to promote to the main site themselves.  This is
exactly what code developers do when cutting releases: ensure that
when a version goes public, it is reasonably clean, consistent, and
complete.

At the moment, some pages, most notably Documentation, are a mess.
Clear out all the "incompletes", and those pages will look like
Cookbook: cool but with gaping holes.  I think that would be an
improvement, particularly if we state on those pages that documents in
early stages of construction are in DevZone, and provide a link.  We
could link those docs at the bottom of Documentation, but there is a
point in a project's life cycle when it would be linked both from the
main site and in DevZone.  Do we want those projects to have two links
on the same page?  And do we really want all that "under construction"
in people's faces?

In the future, we will have good docs and a more spanning set of
recipes.  At that point, if we have embraced the pure Wiki Way, we
will have a hard time agreeing no longer to do early construction in
the main site.  The loads of construction between the gems will turn
away many of the huge class of non-expert users.  SciPy will thus gain
fewer users, and therefore attract fewer contributors and grow more
slowly.  My point now is to get our community culture to include a
sense of professionalism and pride about what we present to the world.
Unless you're a fool or you have no competition, you dress well for a
job interview.  We're not fools, and we have very healthy competition.
The main site is the first impression we make on new users.  My goal
is to prevent it from being the last.

--jh--