[pydotorg-www] project plan (and the "agile" label)

[Paul Boddie]

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>  
wrote:
> >> 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 
planet.

> 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 
account.

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.

Paul

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.