[pygtk] General Query

[Rafael Villar Burke (Pachi)]

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