Gnome Documentation

Rich had an
interesting blog about a Gnome book
. One of the things I found
interesting about it was that his proposal shares a number of
similarities with the
Developing with Gnome
guide I wrote for gnome-love (and which I
need to get back to and add more info, update, etc.). I thought it
might be fun to compare and contrast. I’d like feedback on whether I
should incorporate more of the things that Rich suggests. Of course,
I’d also love to have volunteers to assist. 🙂

Rich’s first introductory chapter covers basic info about the Gnome
project, guides for users, bug reporting and similar things. I really
don’t cover this kind of information at all. I do have a section in
my guide on
building gnome from CVS
, but what I have is probably much
different in scope since it tries to also provide general methods for
overcoming build obstacles (I think I’ve only once ever had a build
from CVS run to completion without any intervention).

Rich then suggests spending the second chapter on choosing a job, todo
lists that exist, and the gnome-love project. I have a section on
joining the Gnome community
, but it is much smaller in scope. I
basically point to a web page that lists the many projects he covers
individually and then mention a little more detail about the bugsquad
or quality assurance team (simply because that is the one I am the
most familiar with). I don’t cover TODO lists at all; I had thought
of something slightly similar but it definitely isn’t included yet.

Rich suggests spending the third chapter on gnome communication,
finding the right person to contact, and other resources. I believe I
cover most of this stuff in my
joining the Gnome community
and
important websites
sections. I definitely don’t have IRC or
finding the right contact for a given project covered, though.

Rich suggests a variety of things for the fourth chapter. First he
starts with development tools. I cover cvs and a number of other
important tools (e.g. pkg-config) in my
general tools
section. I do not cover autoconf, automake,
libtool, and popt (command line parsing)
on purpose
, although I do
explain what they are and what they are used for
and provide
links to outside tutorials
. (Update: popt isn’t covered in those
two sections; instead it’s in the overview of Gnome and related libraries–see
below) I have a section on
common filenames and filetypes
which explain some common support
files but I’m not sure if that’s what Rich had in mind. I don’t cover
anything on saving state, and I don’t have anything specific on
usability, i18n, l10n, or a11y.

Rich’s fifth suggested chapter provides an API reference, an overview
of various libraries, language bindings, and glade. I don’t have an
API reference, but I do have an
overview of Gnome and related libraries
, and I cover gtkmm,
gtk2-perl, and pygtk bindings pretty thoroughly (all examples in the
tutorial are provided for each of those bindings). I give
glade
and
libglade
prominent coverage.

Finally, Rich suggests some extra things at the end. I cover
pkg-config and provide links for autoconfig, automake, and libtool,
but I don’t cover any of the other topics.

My tutorial also contains some things Rich doesn’t suggest. Namely a

debugging chapter
that covers gdb, strace, and valgrind, and also
the chapter I have on building Gnome from CVS that I mentioned
earlier.

So, those who have read this: Which of Rich’s topics would fit well
with my tutorial? Which topics have neither of us thought of that
need to be covered?

Rich: Perhaps we could collaborate? I don’t consider my guide
complete, and you clearly had a number of ideas that didn’t even occur
to me. Even if we have goals that are different enough to warrant
separate projects, it may make sense to share some work in the areas
we have in common.