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

Re: [pygame] how to remove spam comments in pygame wiki



Hi Brian,

Brian Fisher wrote:
On Wed, Jul 29, 2009 at 11:55 AM, jug <jug@xxxxxxxxxxxxxx <mailto:jug@xxxxxxxxxxxxxx>> wrote:

    Yeah, sorry. It uses simple text files with an own simple
    structure and markup. So, it's not as bad as I thought. But still
    bad. IMHO, bad enough to be replaced.
    It *is* something self-made, the html and css is *hardcoded* into
    the generator script and therefore it *is* impossible to change
    easily. Finally, the output *is* ugly and *invalid*
    (http://validator.w3.org/check?uri=http%3A%2F%2Fwww.pygame.org%2Fdocs%2Fref%2Fsurface.html).

    However, after some trial and error and some changes on the
    generator code, I got the docs integrated into the website (used
    code from svn, so docs are for pygame 1.9.0):
    http://pygameweb.no-ip.org/docs/

    So, if no one is interested in a more professional documentation
    system, we should at least update the generator script to produce
    some more valid code, use a simple template for html and css and
    become a bit more configurable.

Julian,
good job on working with current documentation content to get a page working. However I have to say that I do not find this page:
http://pygameweb.no-ip.org/docs/

to be any improvement at all over this page:
http://www.pygame.org/docs/

I don't think the aesthetics or usability have been improved. But my real critique of it is that you dropped what I considered to be a highly effective and useful format for documentation - to have single page docs for a module, where the top half of the page is functions for the module that links down to the dull description later on the same page.

The problem is that with your main page being a list of all modules and their functions together, it's hard to get a good overview of the modules compared to a list of each module with short descriptions. Likewise, once I've decided a module is for me, and choose to go to it's page to drill into it, I don't get a clear and simple overview of that module.

I hope the doc pages are something you continue to improve from the perspective of easily getting overviews of things and getting a high level picture of what the library has to offer.

And lest you think I'm biased, I didn't do a single thing to work on the current pygame website or doc system, and have no particular love of the current website. I just happen to have had a really great experience working with pygame's website doc pages over the years - it's always been a lovely experience to browse them for me because it's so easy to get a high level picture and find what I want. I find them to be far more usable and effective than python's own doc web pages, which are at times overwhelming and impossible to get a good high level view from (like say the urllib & firends docs for instance - where you don't even know what classes or modules you want to use, and once you do have a guess at that, it's hard to find a useful function).
Indeed, the docs at pygameweb are not better than the ones on pygame.org.
I just had a look into the generator script and modified it to produce templates I can use with the rest of the website (so that the recent-releases and the menubar are still there). Then, its valid XHTML 1.0 Strict. Surely it needs more improvements. I'll try to get the index page clearer, for the rest, I don't know yet. Eg. http://pygameweb.no-ip.org/docs/surface.html ist not really easy to read, but I don't know exactly why.
Feel free to help improving it.