Re: [java-gnome-hackers] considerations invovled in writing Tutorials
Brought to you by:
afcowie
Menu
▾
▴
Re: [java-gnome-hackers] considerations invovled in writing Tutorials
|
From: Andrew C. <an...@op...> - 2008-02-25 05:42:12
|
On Mon, 2008-02-18 at 16:28 +0100, Bruno Dusausoy wrote: > Since I'd like to participate - even a little - to Java-Gnome > development, I had the idea of converting the Gtk+ tutorial into Java, No one can tell you "no" in the Open Source world. If you want to go to the effort of doing that, go ahead. I do want to suggest you do otherwise, however, so I've written at some length my thoughts on this topic. ++ My personal view is that the original GTK tutorial is not very well written. I do recall that I didn't find it any help whatsoever when I was originally trying to learn GNOME programming, which further sours my opinion of it. That doesn't mean that the people who wrote it so long ago didn't work hard on it - just that I didn't find it worked for me. Tutorials are hard to write because you have to put yourself in the position of the person learning for the first time, figuring out what they DO know (their context), what they need to know, how to explain it to them, and how to get them to the point where they can take over learning for themselves. Have a careful read of the definition of "approachability" at http://java-gnome.sourceforge.net/4.0/objectives.php and in the original discussion of audience in the doc/design/ documents you'll see what I mean. > just like PyGtk did. Rather than just complaining, one should note alternatives. Here are two things to think about: 1) the Cairo tutorial is *FANTASTIC*. For one thing it was written with translation into other [computer] languages [binding Cairo] in mind. More importantly, it's *well written* and interesting. Even if you have no interest in drawing things, go read it. It's really well presented. So are their "samples" which is the calibre level I've aimed for in our doc/examples/ section, though we've still a ways to go. [Incidentally, a really excellent conversion project for someone would be translating the Cairo tutorial document, using it as a guideline to inspire them to get on with exposing what needs exposing in java-gnome] 2) The other stylistic source would be the "Writing Really Rad GNOME Applications in GTK using C, Java, and Python" tutorial presentation that Davyd Madeley and I wrote give fairly regularly. Since I have explained GTK fundamentals to people on numerous occasions, I have fairly strong ideas about what needs to be covered and how to go about it. I've started converting that to written form, but frankly, giving that talk at conferences is more fun. [And frankly, the topic needs treatment at book length. As it happens, I've already started down that road, which is why I've been spending so much effort on publishing toolchains lately] That doesn't mean that you can't work on something of your own. But if you haven't got a fair bit of experience a) explaining what defines the GNOME Desktop, b) teaching people how to use GTK, and c) detailed knowledge of how java-gnome works these days, then I would recommend holding off and instead concentrate on working on applications of your own [or working with someone like me on one of mine :) :)] and then helping others get going with our bindings of GNOME so as to gain that experience. > So, my question(s) is(are) : Does this kind of project already exist ? > Is there a argument against this idea (API changes or whatever blocker > may be) ? No, just the stylistic issues I have observed above. I don't think that the GTK tutorial which was written 8-10 years ago is very well done, and so personally am not than impressed by the idea of converting it. Most importantly, the material there is dated, and doesn't really talk about what it takes to make a good GNOME application, and that's the most important part. ++ Thinking back to approachability, it's possible that a better approach than converting that monster book might be to make (much) shorter tutorials targeting more specific audiences. For instance, (and I'm just brainstorming here): - Considerations involved in switching to GNOME programming if you've been using Swing - Considerations involved in switching to GNOME programming if you've been using SWT [I have no interest myself in writing such a document, but it basically boils down to the tasks of teaching them to let go of the bad habits the limitations of those toolkits might have forced them to pick up. More importantly, GNOME is a different approach to human machine interface, and so the real challenge is to help people let go of the insane compulsion to micromanage layout design and instead to embrace the malleable user interfaces that result from embracing our approach to these things, rather than fighting against it] - Notes on using GTK in Java for those used to writing GTK applications in C [as I've observed elsewhere, such people are wizards. The challenge here is partially to explain how to do reasonably good Java programming (because they probably don't know, for example, the layering and structure patterns that pay off in Java), and how the conventions that they might have taken to be part of GTK (which aren't, they're just what you do in C 'cause you're in C) have translated to Java. All in all it's another case of "letting go"] As you can see, both these cases have very different audiences, but in each certain things can be taken for granted.(ie, in these cases, people already have some idea about how event driven programming works). If someone is going to work on a document along the above lines, by all means, and I invite people to have some fun pointing out how things work and how they're not a pain in the ass like they are elsewhere :). There is not holy writ saying that Java is better. Far from it. Unless you are already quite proficient in IDE toolchains and in how we do things, then something like pygtk is an order of magnitude "easier" at the start. I can (and frequently do) construct an argument about why Java is a sound choice for projects which are going to scale into the hunderds of thousands of lines of code, but frankly, unless someone is already been down that road, they're not going to listen. Most of all, I have no interest whatsoever in tit-for-tat evangelism. We have made everything in java-gnome the way it is for a reason. In cases where you are attempting to "convert" someone, then we have to drag ourselves through the morass of people whining about "why is it like this" or "why isn't it like that". The answer is "because this is the design we arrived at after 22 months of careful research and engineering (in the case of the 4.0.x series) or, in some cases, greater than 10 years (in the case of the project as a whole) of work, and so that's the way it is". Which is why "convert" is really the wrong word. If someone is giving the library a try and needs a nudge in the right direction, by all means. But you don't want to get sucked into an defencive argument online about "why yours is better", and I want to make sure a similarly defencive tone doesn't make it into any documentation (tutorial or otherwise) we add to the project. It doesn't do anyone any good. So have fun, be precocious, but above all be knowledgeable and positive. ++ As a final thought, I will make the following observation about our API documentation. It's has been winning an unbelievable amount of praise from people. The GNOME hackers in the room last year at GUADEC last year were *stunned* when I showed the quality of documentation that results from the particular style of JavaDoc that I have enforced. I have described it from the beginning as "tutorial style" and in most places it is just that. While that is not a substitute for whatever is ultimately going to live in doc/tutorial/, our API docs are already a good source of tutorial information about _how_ to use java-gnome, and so anyone with an urge to contribute and who has knowledge with the underlying GNOME libraries is more than welcome to do so by offering patches to improve the JavaDoc further. ... if you ever have a question about how to use something, and the help hovering over your cursor in a tooltip doesn't explain it, then the bug isn't fixed until the JavaDoc *does* explain it. That's a wonderful place to contribute. bzr branch, baby. AfC Sydney P.S. Anyone who read this far wins a hero biscuit! -- Andrew Frederick Cowie Managing Director Operational Dynamics Consulting, Pty Ltd Sydney +61 2 9977 6866 New York +1 646 472 5054 Toronto +1 647 477 5603 London +44 207 1019201 We are an operations engineering consultancy focusing on strategy, organizational architecture, systems review, and change management procedures: enabling successful use of open source in mission critical enterprises, worldwide. http://www.operationaldynamics.com/ |
