Hi Pietro, On 25/03/2010 12:24, Pietro Battiston wrote: > But googling for "acire site:pygtk.org" returns nothing. Instead, if I > go to the pygtk website, I'm pointed at a very obsolete and incomplete > tutorial. > The tutorial is incomplete, but not really so obsolete, though it could benefit from some recent niceties ;).
Acire/python-snippets is a very young project and I just haven't really had a deep look into it, but it was an example on how work on related projects can be seen as useful contributions to PyGTK. For instance, I've myself read about it in Planet Gnome and I'd love that it had a website and more end user oriented information in such a place instead of a moving blog. That way it could be made more accesible from the PyGTK website. The point I was trying to make with it (besides giving awareness) is that there are lots of ways to contribute documentation and some of them, like publishing articles in a blog don't have the drawback of potentially blocking on other people apart from the contributor. Most attempts to contribute docs die, AFAICT, because people don't find a way to get started without requiring too much hand holding, due to the false thought that they need to follow a rigid workflow to contribute to the project, and that's a pity. That's why I believe it is better to publish a version of the new doc on the web (as in "release early, release often") and let more people review and comment on it while it matures. Later, those contents can be integrated into the main docs if they have been written with that goal in mind or someone contributes the time to do it, but switching them to gtkdoc, commiting to the pygtk-doc or pygtk repo and getting someone to upload the contents shouldn't be a big problem once the work is done. > So if I was to say what documentation needs more help, I would say that > apart from the API reference (which sometimes it is hard to develop > without being very expert in some details), it is certainly that > tutorial, and in third place the FAQ, which is partly obsolete. > For people wanting to help with the FAQ, the password can be easily found searching the mailing list archive (or asking for it in the #pygtk IRC channel) as it's there mainly to avoid spam. It is a very welcome contribution though I feel like new content is usually contributed by people having really specific problems while developing and when solved they want to contribute back and put it there as a reminder. > Mark Mruss's articles are instead very interesting and linked (I had > already came across them), but intrinsecally static: by reading them, I > never know if what I read is obsolete. At least, by looking at the > tutorial I _know_ it is! > That's why articles are ordered in chronological order in the pygtk articles section, but its static nature can be only overcome by new updated articles or someone doing the continuous effort of updating them, and that's not a realistic commitment for a volunteer driven job ATM. > So apart from expressing my wonder reading the answer given above, I > wanted to ask: if I don't have a _lot_ of time, but I do have the time > to fix, update or extend some parts of the tutorial, the right way to do > it is through bugzilla, by opening a bug in pygtk -> documentation and > then attaching a git patch? > Yes, bugzilla is the right way to avoid getting the work lost and push little bug fixes, text corrections, or contribute to the reference docs as it allows the maintainers to have a look when they have some time. Don't hesitate to ping me on IRC (pachi) to catch your attention (as I only have a look to the bug list from time to time and I suspect others are doing the same). Regards, Rafael Villar Burke _______________________________________________ pygtk mailing list [email protected] http://www.daa.com.au/mailman/listinfo/pygtk Read the PyGTK FAQ: http://faq.pygtk.org/
