On, Wed Jul 29, 2009, Julian Habrock 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. I absolutely agree with Julian here. There was once the pretty nice PCR (which is dead nowadays) and we could have a similar benefit with an own snippet application embedded into the website. It might, with all nifty stuff (and automated user logins), do lots of people a big favour with rating, commenting, stable cross-referencing and external links. For those, who do not care or just want to share two lines of fancy code, there's still the wiki. However, integrating some additional, specialised search, which uses one or more of the bigger search engines, would be a plus, too. > > 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. If we keep anonymous comments, we _must_ take care of keeping the website clean. Spam and worthless junk is annoying, degrades the impression, people have (especially first time visitors) and makes searching for the useful stuff harder. I'm fine with whatever suits more, but keep the above in mind. > > 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. The statement about the documentation system not being changed (made some months ago), is something I cannot follow on. I am not sure, what might be the best for a good looking, scalable and well designed documentation system, but the current one will not fit any of those needs without reworking nearly anything of it. Python's switch to its new documentation system can help us here, too. Since I reworked the documentation system completely for pgreloaded, I strongly vote for moving pygame's documentation to Sphinx by time (not necessarily for the 1.9 series, but absolutely for >= 2.0, whatever it will be). Sphinx has excellent features, allows us to do a lot of tweaking, eases the integration of new stuff and has a (more or less solid support for different formats (HTML, Postscript, PDF, Text, etc.). > > 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. Seconded. The original idea behind comments integrated with the documentation was to allow users to comment on unclear documentation, so we can improve it. On improving the parts, the comments should be deleted. We did not manage to do so for both parts, which is bad. Personally, I would like to keep comments intact, but instead of having them directly _within_ the documentation, I'd rather have the documentation parts to link to an own section in the wiki, which in turn references back to the original documentation. That way, anyone can share thoughts about the comments, add examples (which could be integrated in the upstream documentation in a next release) and so on. The documentation itself would stay clean, revising anything would be easier as admins as well as users can help to keep comments up to date with changes in the documentation. Regards Marcus
Attachment:
pgp0vHJ3FSwFp.pgp
Description: PGP signature