On Thu, Jul 30, 2009 at 4:55 AM, jug <j...@fantasymail.de> wrote:

> Hello,
>
> René Dudfield wrote:
>
>>
>>
>> On Tue, Jul 28, 2009 at 8:39 PM, jug <j...@fantasymail.de <mailto:
>> j...@fantasymail.de>> 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
>

This has already been discussed, that's why.  Obviously the website has been
like this for a while, so at some point you'd think there was a discussion
about it already?

Obviously the documentation should be improved from the doc comments...
that's one of their main purposes.

Reply via email to