It is well known that the developer documentation for Gnome has been
sub-par. As far as I can tell, most people believe that this was due
to incomplete or missing documentation. I did too for a while. But I
believe it was similar to the mindset that prevailed with desktop
linux a few years ago–the belief was that to improve the desktop we
just needed to match all the features found on proprietary desktops.
Over time, people began to realize that we needed more than features,
we needed an intuitive and easy to use interface as well (something
which was the exact opposite of what then existed in the linux desktop
world). I believe that most developer documentation I have run across
for Gnome that is of any significant length has an analogous problem,
and is simply unfit for beginners. This would not be so bad if that
documentation was merely used for advanced developers or dedicated
intermediate ones (for both of whom it can be very useful), but it is
exactly where beginners are pointed when they are trying to get
started.
There are a couple of ways documentation has been bad for beginners.
Perhaps the most aggravating is that it feels like there has been a
systematic misleading of beginners into a quagmire of irrelevant
details. (That is, irrelevant to the beginner. The details
really are relevant to the experts for large projects, and the reason
this problem occurs is simply because experts write about what they
use when they document, forgetting that it may not be the best way for
beginners to start.) I have even written
about this in the first section of my developing with Gnome guide
as a warning to beginners who will probably run across this multiple
times as they try to learn. I sure did. Unfortunately, I have to admit
that I am also guilty of pointing other beginners in those same
directions (it was where I was directed by others, so I did the same
thing when others came along… *sigh*).
Another problem is I guess what you would call lack of integration.
For example, I have tried to find many tutorials on glade and
libglade. I was not able to find any tutorial that really covered
both. Either they covered glade and gave only peripheral (if any)
coverage of libglade, or they covered libglade and assumed you were
familiar with glade. The tutorials that covered glade would then
point out how to use it to do automatic code generation, instead of
showing how to use libglade. But
automatic code generation is discouraged. Having a developer find
that out after they have been using it for a while is definitely not
optimal. And many projects continue to do just that because glade
tutorials showed them how to do it, and did not show them how to use
libglade. If one wants to use glade and libglade together, one has to
read glade tutorials and libglade tutorials, and then try to piece
things together despite the different tutorials using very different
examples.
Another problem that exists is ignoring the need for cohesive
documentation for important non-programming items and tasks, e.g. what
utilities are used and how does one use them (diff, patch, pkg-config,
etc.), an overview of what webpages are important for Gnome
developers, important debugging tools (gdb, strace, valgrind, etc.),
and how to build from CVS. This can be problematic in a couple
different ways. One is that the beginner can hear about tasks that
need to be done (e.g. “submitting a patch”), and not know how that is
done (e.g. “how does one make a patch? Is it something one creates by
hand, or is there a tool or a set of tools that do it?”). Another way
is that they might find a hard way to do something since they are
unaware of resources that exist (e.g. reading through their entire
source code slowly and carefully to try to find a memory leak instead
of using valgrind, or struggling to understand how to make a dirt
simple UI look decent instead of reading the HIG for some great
guidelines and specific examples with details). Finally, yet another
way this is a problem is that the beginner may know that a certain
tool, such as gdb, will be useful to them but they only need to know
the basics in order to make good use of that tool. They then ask
someone for a guide about gdb and are then pointed to an
official online manual that is a few hundred pages in length and
is meant to describe the tool thoroughly; yet a simple quick start
tutorial that is a few pages long which would take them 15 minutes to
digest would have been much more appropriate.
That covers the major problems, though there are others. But this
blog entry is getting long enough. So to wrap up, let me just say
that I have this theory that some of the general usability principles
in the
HIG can be interpreted in such a way that they provide great
guidelines for how to write documentation. I will cover this little
theory in my next blog entry.