Il giorno mer, 24/03/2010 alle 11.27 +0100, Rafael Villar Burke (Pachi) ha scritto: > 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
I certainly have no authority to say what documentation pygtk mostly needs to put work on. 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. 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. If you think that acire is more important, it should really be integrated somehow in the pygtk "officially suggested" documentation. I use pygtk a lot and had never heard about it. 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! 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? Pietro _______________________________________________ pygtk mailing list [email protected] http://www.daa.com.au/mailman/listinfo/pygtk Read the PyGTK FAQ: http://faq.pygtk.org/
