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

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

Hello,

René Dudfield wrote:
On Tue, Jul 28, 2009 at 8:39 PM, jug <jug@xxxxxxxxxxxxxx <mailto:jug@xxxxxxxxxxxxxx>> wrote: 

    Hello,

    We are still working on the pygame website rewrite. I'm currently
    implementing a snippets
    app that should replace the cookbook section in the wiki. The code
    is handled as code,
    apart from the description. Thus, you can download the snippets
    directly as .py file. Then,
    its easier for everyone (who has an account) to add new snippets,
    to find useful snippets
    and to remember them.
There's a cook book and code search for this now. This searches the 1000s of projects on the internet for each use. It's much better than a snippet section you decided on.
Well, I can add a google search, too, but seaching is not the main point here. A wiki is not designed to manage code snippets. Surely its possible, you could even manage projects in a wiki, just give each an own page. In my opinion, a snippets app is more user-friendly. You have one snippet, one description text and one author. If someone has a good tip, he should be mentioned when sharing it with the community. Users can review the code and tell in a comment if it helped them or not, if there is something to improve etc. I know, it may be new to you and not convince you directly, but while development, I got a lot of useful tips and snippets from http://www.djangosnippets.org/. 
General tips, tutorials or other stuff can still be handled in the wiki.


    Since comments will be reserved for registered users, number of
    spam comments and other
    waste content should decrease a lot. For the rest, we may have
    something like "mark as spam"
    buttons, so you can tell the site admins directly if you notice
    any spam.
why do you get to decide this? Many of the valid comments are made without login, those would not exist if it required a login.
Well, I discussed that with Marcus. I think that there will be more users with an account (or more users, that actually already have an account, will login) if there is more than just projects. Currently, you just login if you want to edit a project, a wiki page or comment on a project. And you get automatically logged-out. On the new site, its more worthwhile to log in, and you can stay logged-in longer, if you don't log out. So most active pygame users should have and account and it's really easy, you just need a valid email address. But besides that, to open comments for anonymous wouldn't be difficult either. 


    Documentation is another problem. I think, with the website
    rewrite, also the docs should
    modernized. AFAIK, The current system is something self-made that
    uses documentation thats
    already written in html. It blends htms and stlyle to one html
    file, so it is quite impossible to change
    the style or to include it to the rest of the site. I don't know
    how the comments work, but it looks not
    good. As well, it would be better to have some kind of api access
    or at least methodical urls to
    access documentation programmatically form the rest of the site,
    the apis or even the attached
    irc bot.
You're completely wrong about the documentation system. I suggest you actually read it before commenting on it.
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. 


    I don't know about all the possible documentation systems and
    generators, but sphinx[1] may be
    adequate. Further on, I'm not sure if documentation should include
    comments. I think it would be
    better to use the snippets section to show really useful code
    snippets (we could link against them
    from the online docs) and for other stuff the wiki. If there is
    really sth. missing in the docs, it should
    be added to them, so also users who download the docs an read it
    offline should see these additions.

    Next (maybe pre-final) testing phase will come soon,
    including the new snippets app and much more.


The comments section is staying.

Why do you get to decide this (alone and without argumentation)?
I admit, some comments in the docs are really helpful, but I'd say that at these few points it's because of vague documentation, and that you should improve the docs there instead of just adding a comments function. If necessary, add small examples of 2-5 lines or so to the docs of particular functions or classes. If users understand documentation only together with attached comments, documentation is bad and needs to 
be improved.


Julian