[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[pygame] Re: Website and documentation issues


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.


[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