[pygame] Re: Website and documentation issues

[jug <jug@xxxxxxxxxxxxxx>]

Hello,

I'm glad to see some more people participating in an objective 
discussion here. That's the only way to get to one good website most or 
all "pygameists" are happy with. It would be bad to start a second, 
competing pygame site.
I cannot quote all last mails, so here is how I see all that stuff.

A Short Summary

At the beginning, that website rewrite was an explicit point on the gsoc 
list of pygame.org [1] requiring  a "rewrite in python" (not improving 
or updating old handwritten php code). Then, it was not chosen for gsoc, 
but we (Orcun and me, later Devon) decided to do it anyway to give the 
community a new website and to extend our knowledge about web 
developing. We asked on the mailing list and the first heated discussion 
came up since some guys seemed to still work on a new website or at last 
planing such since January or so. We were arguing in a circle for some 
time, then wanted to be more productive and started developing and 
announced that on the list. We built the website on the basis of the 
pygame.org wiki [1] [2], opinions from mail, #pygame and Marcus, and 
certainly our own ideas and experiences. Now and then we posted a link 
to the preview and got a little feedback what to improve (mostly about 
the design).
We could not ask on the list for every detail, cause there were so many 
of those and often you can do it so or so, but it amounts to the same 
thing. If we had some new ideas or wanted to change anything from the 
old website (documentation system, comments, snippet, ...) we got a 
"no." without explanation that did not really help us. Anyhow, I think 
we should have asked more here.
Because we were more or less convinced to replace the current website 
one day we would finish, we asked for the current database or a part of 
it to write convert scripts to migrate data. Every time we asked 
(whomever), we got a hopeful "yes, next week" or so. But nothing 
happened. The rest is well known.


Current Status

We are not done! Most of the things we've planed [3] are done. The 
snippets app is not yet finished and a voting app not even started. I 
generated the documentation from the current system since its not 
possible to change that for now. As well, the style is not yet finished. 
Some details and the style for the snippets pages are left. The Trac 
style needs to be updated, too.
After that, we plan(ed) an extended testing phase to let all of you test 
the site and tell what to improve, change or fix.
Then, some day, we'd be ready to migrate data and set up the page on 
another server.


About Design

I just want to mention, that we strongly plan alternate styles. The 
current style has a relatively high min-width, but its not possible to 
reduce that for this design. Then next style will be simpler and more 
flexible, ie. better adapted for low resolution, small windows, old 
browsers etc. I'm sure it would be even possible to make multiple 
versions of one style, so an "wide screen" version with some larger 
max-width or so. If you login to the demo page and go to the 
edit-profile page, you'll see that we already have a theme-option to 
change the style used with this profile (currently, there is just a 
dummy alternative to test it).


About Documentation

The current documentation works and produces output you can work with. 
But it could be better in several points. I think some more markup could 
be one. A bit more structuring and navigation another. Most 
documentation, I'm currently reading, is about Django [4] that uses 
Sphinx just like many other projects [5]. Django is a large framework 
and I had no problems with the docs yet. But also smaller projects with 
less documentation use Sphinx, so I don't thing it would be oversized 
for pygame. Then, it uses reStructuredText with some extras, thats makes 
it easy to write much more than plaintext docs.
All in all, I think the current docs are usable, but could/should be 
improved. And Sphinx fits the bill.



Regards,
Julian


[1] http://www.pygame.org/wiki/gsoc2009ideas#Pygame%20website%20rewrite
[2] http://www.pygame.org/wiki/todo#Website
[3] http://pygameweb.no-ip.org/trac/wiki/Features
[4] http://docs.djangoproject.com/en/dev/
[5] http://sphinx.pocoo.org/examples.html