[python-advocacy] How programming language webpages should be designed

[Paul Boddie]

On Sunday 08 November 2009 14:43:51 Jason Baker wrote:
> > Jason Baker has interesting thoughts about how programming language
> > web sites should be designed, and criticizes python.org for not
> > putting code examples on the front page:
>
> It's worth pointing out that I didn't intend for this post to just be
> a criticism of python.org.  For the most part, python does all of the
> things that I list well... except what is in my opinion the most
> important one.

I think your point is a very good one, which is why I responded to your blog 
entry in a comment.

> That said, I won't be the person who sits back and criticizes without
> trying to change anything.  Here's what I would like to propose:
>
> Have a set of simple examples (on average 4-5 lines, no more than 10)
> that demonstrate most of Python's major features  and link to them on
> the front page.  Something like this:
> http://wiki.python.org/moin/BeginnersGuide/Programmers/SimpleExamples

I've added syntax colouring to these examples. Please revert the change if you 
don't like it or think that it's distracting.

> I like this format because the examples are easy to understand, and
> they show off Python's strength:  readability.  I think that most
> people who have a bit of programming experience will be able to figure
> these out without too much description or even any interactive
> interpreter output.

Yes, I think it's perplexing that Python's readability is promoted as a 
strength and yet there's an apparent reluctance to show any code.

> If this is something the community wants to go with, I'm willing to
> put time into writing this page.

I want to encourage you and others to improve these resources. I recently 
stumbled across the "simple programs" page again on the Wiki, which was an 
initiative to show off programs of increasing length and complexity, but this 
brings me to another area of concern: some of the programs had been hastily 
modified to work with Python 3 - changing print statements to functions, for 
instance - and this actually changed the behaviour of the affected programs 
(the editor concerned was obviously not motivated to change them all) as well 
as making the programs inconsistent with the text.

I suppose that this is another concern with Python 3 (which I'm sure I've also 
mentioned before): if one promotes Python, should programs use Python 3 
syntax and features when many people will still be encountering Python 2 
programs? It doesn't help that right at the very start of a beginner's 
experience with Python, there's a divergence between the dialects involving 
the print statement.

Paul