I just committed a Metacity patch to CVS to add support for
_NET_WM_USER_TIME. Unfortunately, due to bugs in current application
launchers using startup notification (e.g. the panel and nautilus),
this means that all applications launched with these launchers will
show up unfocused and behind the focused window. Applying the
patches^Wugly hacks in bug 136278 and
144897 will fix that (even if they do so The Wrong Way(tm)).
Archive for June, 2004
I just committed a Metacity patch to CVS to add support for
Spent quite a bit of time this past weekend on fixing various things
in bugzilla and updating the
guide. Unfortunately, I only got a few things done with each.
But, at least the weekly bug
summary is running again and cron jobs are in place to update the
which are resource intensive.
I’d like to take just a minute to thank the tireless sysadmins. I
bugged them a lot this past weekend (if they had a list of pests I’d
probably be on it) about cvs issues and httpd error logs and such.
Their job is one that often goes unnoticed by most, but it’s a very
important job that they put a lot of time into.
As promised before (although later than I promised), here is my theory
on how some of the
general HIG usability principles can be interpreted in such a way that
they provide great guidelines for how to write documentation for
beginners. Note that this may not make sense without reading my
Gnome Developer Documentation blog entry or my other follow up entries.
Don’t limit your user base
Applied to user interfaces, at the most basic level, this means
things like not requiring first time linux users to compile
their own kernel in order to try linux out. At a higher level,
it means things like taking care of a11y and i18n, among other
Applied to documentation and taking the more basic level
approach, it means not requiring beginners to learn autotools,
compiling from CVS, or some other similar expert project. One
of the higher level meanings (though I don’t believe this is
actually a good idea for most documentation, at least not in a
single work) could be to include other language bindings so that
you don’t lose all the programmers who don’t know C.
Keep it simple and pretty
For user interfaces, this is just a result of the fact that
feature-ridden applications confuse beginners, slow them way
down, and turn them away.
For documentation, the problem is the
i-must-be-comprehensive-syndrome. Beginners usually just want
the basics of a given library or tool, not every detail about
how it can be used.
Use familiar terminology
For user interfaces, this can mean things like including the job
of an application in the menu entry instead of just using the
application name (e.g. “Mozilla Web Browser” instead of
For developer documentation, this can mean things like
describing libraries according to what they are used for, not by
the technologies they employ. (e.g. Describe libxml as “These
libraries provide fast parsing of XML (Extensible Markup
Language) files. XML is a file format which is often used for
configuration files, documentation, and many other things.”
instead of “Powerfull and feature complete XML handling
Let users know what’s going on
For a user interface, this means things like providing an audio
beep, error messages, or progress indicators.
For documentation, this could mean giving budding developers a
high-level overview of what they will need to learn.
Put the user in control
I also like to think in terms of “reward the user”, which I
think is closely related. From the HIG it means things like
avoiding modes so that users can switch between applications and
windows at any time.
Developers reading documentation aren’t in control–they’re
trying to gain control. Developers who are working on a project
are in control. Thus, it’s important to give developers small
projects to work on early, and to get to simple yet useful
examples as quickly as possible.
Make your application consistent
For user interfaces, making your application behave similarly to
other applications enables users to apply their existing
knowledge of their computing environment and other applications
to understanding a new application. Making things inconsistent
means the user runs into surprises when using new applications
that slow them down or make them lose a sense of trust in the
For documentation, people try to apply their knowledge from
reading books they bought at the store to Gnome documentation.
Most developer documentation starts with the basics, however
Gnome documentation starts with the nitty gritty. Thus, new
developers feel “Wow, the basics are this hard? There’s no way
I’ll be able to master even the intermediate stuff, let alone
A few more thoughts I’ve had on the developer documentation subject:
Gnome documentation tends to dive into advanced details upfront
(e.g. autoconf, building from CVS, low-level glib and gtk details,
popt, gettext and other i18n stuff, etc.) This is the stuff given to
beginners. Thus, the subconcious message is that you have to master
all this stuff to get started. If one has to master these details to
get started, what must one master to actually be able to write
documentation? …Is it any wonder that few have been willing to
write documentation? Also, is it any wonder that new developers get
discouraged? (The thought is “If these are the basics, how can I
possible master the intermediate and advanced details?”, not
understanding that they were thrown to the advanced details already)
Bonobo is the component object model of the GNOME (Gnu Network
Object Model Environments) project (it is also a monkey — see
Resources). Bonobo provides a COM-like model, using CORBA as a
That was so helpful. What in the world is CORBA and COM? A year or
two ago, I literally tried to read up on those things for a couple
hours and still didn’t have a clue what libbonobo was. Yeah,
I’m stupid and I should have been able to figure it out in much less
time (or just bug people more on IRC or the mailing lists) but
that doesn’t change the fact that it is a problem. Here’s another:
libXML is a powerful and feature complete XML handling library.
Really? I would have never guessed. So what’s XML? (That’s
rhetorical, I do know the answer now and have written my own
overview of Gnome and Related libraries.
After pointing some people in #gnome-love to my blog entry about The Atrocities
of Gnome Developer Documentation, we had a great discussion. It
was comforting to note that others agreed with me, and some of the
particular things others said were interesting. Here are some of
those conversations (edited slightly to try to make things more clear
than the normal IRC flow).
<Misirlou> I think that the documentation for beginners should assume that the reader knows absolutely 0% about UNIX-style development. <Misirlou> "Generate a patch." <Misirlou> "Okay." <elijah> yeah, that's how I felt too when I heard it... <Misirlou> (Smart developer goes to RTFM on patch.) <elijah> and then discovers that the tool they need is called 'diff' <Misirlou> "Okay, so I need to run the diff program. Where do I run it?" <elijah> and then wonders what order the files need to be in... <Misirlou> "Wait, your patch was not in the right format. Also, your indentation is all wrong." <elijah> ah, this brings back so many memories. <Misirlou> :( <fer> I would like to have a _big_ developers meeting about that <fer> most of hackers are really good, but sometimes don't take care on social relations with newbies <fer> so they are discouraging then <fer> maybe the people from gnome-love should teach them just a few things :) <elijah> there's more to it than that... <elijah> as I said in my blog, the documentation is nearly impossible to wade through, making it hard for new people to feel comfortable with their knowledge.. <elijah> so, when a new user comes along, those who were in that position not too long ago don't feel comfortable answering questions... <sri_> indeed <sri_> the quality of our docs suck <elijah> so instead, they point the newbies to the docs... <fer> to the wrong docs <elijah> and the newbies feel like they received a "fend for yourself" response. <elijah> fer: yup <sri_> yeah :( <sri_> and what you get is only a subset of people who are willing to slog through the docs and the source. [Editorial note: also, those who probably could answer the question are busy hacking and thus aren't available to answer the question; which is why those who are less certain of themselves try to offer a guide they are aware of, but the newbie definitely doesn't know that.]
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
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
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
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.