[pydotorg-www] project plan (and the "agile" label)
paul at boddie.org.uk
Thu Apr 22 01:25:42 CEST 2010
On Wednesday 21 April 2010 23:37:12 Michael Foord wrote:
> On 21/04/2010 20:56, R. David Murray wrote:
> > On Wed, 21 Apr 2010 12:31:00 -0400, Richard Leland<rich at richleland.com>
> >> I agree with Michael - as someone that is getting familiar with the
> >> process it just doesn't seem as agile as it could be. For instance, if
> >> there was a decision to add 5 new sections with 30 pages of content,
> >> which method would be faster for updating - a through-the-web-based
> >> approach or the existing create files, check in, build?
It depends on what people think "agile" means. If you're doing bulk updating
of stuff, you probably need a more efficient approach than manually creating
Wiki pages, say, and copying the text in. That said, there are ways of adding
content in bulk to a Wiki.
> >> I'm not sure one
> >> is faster than the other and I'm sure there would be varying opinions on
> >> that. Maybe the way to approach this question is thinking about who
> >> could be editing the content. Should it always be technical individuals
> >> or should someone with writing skills be able to update the site as
> >> well?
The "consensus" in python.org circles until now has been to keep access
restricted to a group of people who are likely to regard the current
technical barriers as acceptable.
> > I'm not a current contributor to the python.org content, but I agree
> > with everything Skip said about this. For people who are (python)
> > programmers, through-the-web editing is not agile. ReST pretty much
> > *is* text. The tools are not hard to learn...and perhaps demystifying
> > them for those who are scared of them would bring more developers into
> > the software community, which would be a great thing. "Writers" can be
> > programmers too, some of them just don't know it :)
Firstly, I have to say that I dislike ReST: I used Zope's Structured Text from
the beginning, and ReST is quite an inelegant extension of the concept, ugly
even compared to some of the nastier Wiki syntaxes (and let us not venture
close to Markdown). I also have to say that if "agile" is getting things done
in an interactive, "low barrier to entry" fashion, than through-the-Web
editing has won. See my note about the other interpretation of "agile" above.
> Right - but it makes the *minimum* barrier for entry to contribute
> changes doing a full svn checkout, making changes in rest format (which
> I'm not proposing we drop as it goes) and then generating a patch (which
> then goes where?).
Agreed. Unless "agile" means something about lengthening the workflow, too. I
think Anatoly has a page describing the documentation feedback workflow and
it isn't pretty.
> For a non-programming copy editor (for example) who wants to help this
> is a *huge* burden involving the command line and a whole bunch of
> tools. Absolutely no need for it to be this arcane. Just because they
> are tools that *we* as programmers are familiar with (and not all
> programmers are by any stretch of the imagination) is no reason to make
> it so complex.
Personally, I'd rather not have very much to do with Subversion, either. I
totally sympathise with the notion of a Web publishing system under a
conventional version control system with a build framework taking care of
content generation, but to some outsider who upon browsing the site sees
something that could be quickly fixed, it's like making them go to another
> There is also no conceptual reason that we couldn't come up with a
> system that allows both ways of working (a through the web system that
> generates patches for example) - but insisting we stick with the current
> system because we are familiar with it and have no reason to change is
> not good.
Well, I don't have access to python.org's content system, but I have been
given the keys to its counterpart on the EuroPython site, and (once again)
while I can see the benefits of such a system, it's not hard to catalogue its
deficiencies compared to a Wiki:
You need a shell account, which is asking for a lot more than getting a Wiki
You need to be familiar with the system layout, which requires that someone
shows you the way or assumes that you can find your way around, whereas most
Wiki interfaces are already familiar to many people.
You need to know the toolchain: a README file helps, but most people's
familiarity is likely to be a lot lower with even a popular toolchain than
with a Wiki.
You also have to like the chosen content format: although people can complain
about Wiki syntax, they're more likely to have already seen, and perhaps even
prefer, such things in comparison to the YAML/ReST hybrid apparently
preferred by the python.org system.
Content previewing is clumsy, although it is possible to change many pages in
one editing session, whereas a Wiki will let you preview stuff quite
naturally in the same interface.
One key measure of whether a system is really doing its job fully in
supporting a collaborative editing environment is whether people have to ask
other people to make some change or other. Another measure is whether all the
responsible people are routinely making changes in an environment, anyway.
For EuroPython, people (even the important people like John) can just go and
change the Wiki, whereas for the main site people have to ask other people to
change stuff. If "agile" is getting your content up quickly, guess which
system is most "agile" there!
So, I draw on actual experience in preference to asserting that vague terms
like "agile" apply to one solution or another. If you want a diverse range of
contributors - people who are motivated to edit that topic guide of
non-interest to, say, the core developers - you're more likely to get them
with a through-the-Web system.
P.S. Although making a grand plan is a positive thing, I'd also like to see
some progress being made on updating the existing parts of the python.org
infrastructure, some of which could usefully do with some long-overdue
updates and upgrades.
More information about the pydotorg-www