java-gnome-hackers

[java-gnome-hackers] Java-Gnome Tutorial

[Bruno D. <bdu...@be...>]

Hi all,

I don't know if this is the right list to ask to; if it's the case,
please tell me nicely ;)

Since I'd like to participate - even a little - to Java-Gnome
development, I had the idea of converting the Gtk+ tutorial into Java,
just like PyGtk did.

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) ?

Regards.

-- 
Bruno Dusausoy <bdu...@be...>
thx1138 on FreeNode

Re: [java-gnome-hackers] considerations invovled in writing Tutorials

[Andrew C. <an...@op...>]

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/