[pygtk] General Query

[Rafael Villar Burke (Pachi)]

I'm forwarding this to the main PyGTK mailing list, as it may interest 
other people.

On 24/03/2010 3:59, David Scott wrote:
> Hi,
>
> I hope this email finds someone who be able to provide some feedback.
>
> I did a Computer Science degree a couple of years back and had to work 
> pretty hard teach myself the material in order to pass the course. It 
> taught me the importance of good documentation. Since switching to 
> Linux a couple of years ago I have wanted to develop a few of my ideas 
> into applications to make available for the community but 
> unfortunately software development in Linux is not as easy as it is 
> for Windows. Open Source is great but the lacking area is always 
> documentation and examples (Google really does become your best friend).
>
> Looking at the tutorials for pyGTK I notice they are five years out of 
> date and too simplistic to be of much use. What the project really 
> needs is a lot more in the way of tutorials - perhaps even examples 
> for each of the GTK widgets used in GUI design. Perhaps I am missing 
> something...is there a companion site where newer tutorials exist but 
> that I have not yet found? Anyway, I would be interested in helping to 
> develop some new tutorials to show new comers how to get started. I 
> don't have a lot of experience with pyGTK since I am still learning 
> myself but my own efforts so far are definitely further along than the 
> tutorials on the site. I think it is possible to really improve this 
> aspect of the site but I can't do it on my own; I'd need someone with 
> more experience to review my output (code and accompanying text) to 
> ensure that I am demonstrating the best way of implementing the 
> widgets. I really don't want to make an idiot of myself by showing a 
> bad way of doing something when there is likely a more elegant way of 
> doing it (and we all know what a vindictive environment it can be when 
> experienced geeks take exception to something that they don't like). 
> Would anyone be interested in overseeing me if I undertook this 
> endeavour?
>
> Why would I want to do this? Well, for a start I have more time on my 
> hands than I can deal with. I am in a foreign country with my partner 
> but I can't work here because I am not fluent in the local language. 
> Secondly, I have been delaying improving my coding skills for the last 
> two years in the hope that some sort of cross platform solution would 
> turn up. Well, nothing much has happened. Adobe's Flex is proprietary 
> and cumbersome. JavaFX showed promise but now is even worse than Flex 
> because Oracle have wrapped their corporate tentacles around it. QT is 
> bloated and ugly to me. And I using ajax frameworks require a 
> supported server. So python and pyGTK remains the best solution for 
> Linux (at least from my point of view).
>
> Please let me know if anyone is interested or, indeed, whether this is 
> even possible.
>
> Kind regards
> Dave

Hi Dave,

First of all, better documentation is always welcome and more people 
working on it is what is needed, so your help is really appreciated!

About the task, I'd give you some general recommendation to try to lower 
the barrier for others to collaborate with you.

This usually means:
- try to get some feedback using the PyGTK users mailing list [1] or the 
IRC channel [2]. If you require specific people to do the review it's 
quite possible that they don't have their free time as the same time as you.
- ask for specific help instead of asking for general review. That way 
people can contribute just spending a couple of minutes instead of 
requiring a long time merely read your request.
- publish your work on a public blog or website. It will be quickly 
available and you'll get comments, review and valuable feedback soon. We 
can later host it at the www.pygtk.org website.
- be specific and don't try to overdesign the whole series. If you start 
covering topics that adapt to your skill level and are just a step away 
from  your current knowledge but need some further investigation you'll 
be able to cope with the task and it's quite possible that others will 
need to follow your same learning process. Also, it makes asking for 
help easier, to avoid implicitly asking others: "Teach me PyGTK so I can 
write it down".
- build upon the existing documentation instead of covering already 
existing topics. It will help fill the gaps and it will interest people 
with different skill levels. Furthermore, rewriting topics that are 
already covered isn't probably going to fly.
- joining other related efforts, like Acire [3][4], may be another good 
way to improve the docs. You could write interesting examples and 
discuss them in a blog post.

Regarding contents, I find the existing documentation very good, but it 
lacks task oriented information. It would be good to have short guides 
or articles on how to install PyGTK on win32 and linux and get running, 
how to structure an application that's more complex than the usual short 
examples (for instance, explain a reasonable simple MVC pattern), how to 
create custom widgets and use them in bigger applications, or how to use 
glade files with gtkbuilder, how to use specific widgets not covered in 
the tutorial, etc.

So, three suggestions would be:
- grow the series by Mark Mruss, whose articles are very well written, 
aren't trivial, and could be a good start point to deal with more 
complex topics.
- try to come with useful PyGTK snippets and add them to Acire so they 
cover a bigger part of PyGTK
- write articles explaining the guts of PyGTK snippets in Acire

Don't be discouraged by the work ahead and enjoy doing it!

Regards,

Rafael Villar Burke

[1] http://www.daa.com.au/mailman/listinfo/pygtk
[2]
[3] https://launchpad.net/acire
[4] http://www.jonobacon.org/category/acire/