On Thu, Jul 30, 2009 at 4:55 AM, jug
<jug@xxxxxxxxxxxxxx> wrote:
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.
yes, I don't care. Feel free to start up a separate website for them.
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.
Why don't you and Marcus work on a pgreloaded website then?
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 really don't see where you get off calling the current system unprofessional.
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