New Guide on Developing with Gnome

[Elijah P Newren <newren math utah edu>]

[Note to list moderator: Mariano suggested I send this to this list as
opposed to d-d-l or elsewhere, even though I am not on this list (yet)]

I have written a guide on developing with Gnome[1].  I feel that it is
different from other Gnome documentation in that it tries to focus on
the beginner.  In particular, I have written a set of guidelines[2]
that I think helps to focus on this aspect.  This guide isn't ready
for general consumption yet[3].

I am emailing to ask for suggestions and comments if anyone has any.
I have already asked people in #gnome-love and on the gnome-love
mailing list.  Also, if you happen to be an expert in one of the
topics my guide covers, it'd be great if you could check that section
for technical accuracy.  You'll probably find it lacking in that
department, and it'll be your fault if I misguide newbies.  :) Hee
hee...

Here is what my guide covers (so far):

  * I start off with a rapid orientation to tools (e.g. diff, patch,
    pkg-config, etc.) and websites (developer.gnome.org (with a
    warning), the HIG, cvs.gnome.org, etc.) that a new developer
    should be aware of, provide pointers on becoming part of the Gnome
    community (this is for those who want to work on applications and
    libraries that are part of the Gnome D&DP as opposed to those who
    want to just write their own, possibly proprietary, applications;
    this includes things like mailing lists and
    developer.gnome.org/projects), and provide some pointers on
    pitfalls to avoid.

  * I then provide tutorials on glade, libglade, and gconf (gnome-vfs
    will be added next, but it may be a while before that happens).
    All examples are provided in C and C++ and Perl and Python (though
    the discussion is biased towards C as my original goal was to help
    more people become Gnome contributors and most apps and libraries
    are currently in C).  As always, my goal here is to give the
    reader just enough information that they can do something useful
    and have some examples to play with--and then refer them elsewhere
    for more comprehensive treatments of any given subject.

  * Next there is a section on debugging tools, currently covering
    GDB, strace, and valgrind.  (Are there any other major ones I
    should cover?)  Again, it's a get your feet wet and learn to do a
    couple useful things type of pace.

  * After that, for those that want to be Gnome developers, I provide
    a fairly detailed guide on building Gnome from CVS.  This is more
    comprehensive than other tutorials I can find on the subject in
    that I also include general instructions on how to deal with the
    snags that occasionally happen and provide examples of specific
    workarounds and fixes for resolving CVS build issues.

  * After this is a chapter that is more of a reference than a
    tutorial.  It is designed to answer the question, "What in the
    World is That?!?", which I found myself asking a lot when I was
    trying to learn.  It includes an overview of Gnome and Related
    libraries (I still need to add most of the freedesktop.org ones,
    though), tools that Gnome uses (autoconf, intltool, etc.), and
    common filenames/filetypes (.desktop, configure.ac, autogen.sh,
    .spec, etc.)

  * Finally, I provide a link to other tutorials or guides that are
    either more advanced or are about a specific (niche?) topic.


Cheers,
Elijah


[1] Available at
    http://www.gnome.org/~newren/tutorials/developing-with-gnome/.
    Note that it's also a work in progress with more additions and
    changes under way.

[2] Which I have titled "General HIG usability guidelines
    reinterpreted for developer documentation", and which you can see
    at http://www.gnome.org/~newren/blog/2004/Jun/05 (though perhaps I
    should include them in the source for the guide?).  Also, I am
    already aware of a couple locations in my guide where I haven't
    followed these guidelines but should have.  It has very much been
    an evolutionary process as I've tried to figure out better ways to
    target beginners.

[3] One advantage I have of presenting things for beginners is that I
    am a newbie myself.  However, that is a two edge sword because it
    means that my guide is just an attempt by the blind to lead the
    blind.  I have tried to get some experts to review it and have
    gotten some people to look at parts of the guide.  A couple
    experts said they would look more closely, but both are already
    overloaded with other Gnome tasks. It should be ready for a wider
    audience after they have reviewed it.