Massive Bug Import

Bugzilla import for Bug-Buddy, unfortunately, had been broken for
months since the upgrade of Bugzilla. This meant there were around
1500 bug reports that had been filed with Bug-Buddy that weren’t
imported into bugzilla. Yesterday, as Fernando reported,
this was finally fixed, resulting in a massive import of bugs to
bugzilla. (Normally, with bug-buddy submissions there’s around 80 new
bugs per day, without bug-buddy submissions it’s closer to 50-60 or
so). This doesn’t show up on the Weekly
Bug Summary, because the imported bugs were dated with the time of
their submission, so the number of “reports opened” doesn’t reflect
reality. When I came in to IRC this morning and read my backlog, I
got to find out what some people had thought about this. Needless to
say, a lot of maintainers were surprised at the influx…

I guess the good side to this is that people attacked (and are
attacking) these new bugs pretty well. The funny side to this is that
the closings of those reports do count for this
week, so our numbers for closings of bugs look about as good as
they ever have (we closed more than twice as many as how many were
“opened” this week, wee!)

Of course, this would be a great time to join the bugsquad and
give us a hand, because we still have an awful lot of bugs to go
through. This would be a great way to show your appreciation to the
Gnome project and help it move forward. <marketing
mode=”newbie attempt”>Make your mark on history, join us
today! </marketing>

For those running a CVS version of Gnome…

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
bug
144897 will fix that (even if they do so The Wrong Way(tm)).

Fixing bugzilla and the bugsquad triage guide

Spent quite a bit of time this past weekend on fixing various things
in bugzilla and updating the
triage
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
reports
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.

General HIG usability guidelines reinterpreted for developer documentation

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
Atrocities of
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
    things.

    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
    “Mozilla”)

    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
    library.”)

  • 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
    environment.

    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
    the advanced.”

Are you bored of this topic yet?

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)

Here’s one of my favorite tidbits. When I was learning, I heard about
the “libbonobo” library. Curious, I wanted to know what it was and
found a description very similar to the following one from
http://developer.gnome.org/doc/API:

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
location-transparent transport.

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.

More comments on developer documentation atrocities

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.]

The Atrocities of Gnome Developer Documentation

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.

Workstation Back

After two and a half months of my workstation being gone for repairs,
it’s finally back. It’s about time. Ugh. The OS was also upgraded
from Red Hat 8 to Fedora Core 2. It’s great to have back, but it
really sucks that the bugzilla installation that I had on it (and
especially the corresponding mysql database) was nuked. I had a todo
list for various bugsquad tasks
that needed to be done as well. Now that my memory has had two and a
half months to wither away, the list is probably gone forever as well.
Sometimes I wish I could just be the admin for the workstation, even
if it would mean that I couldn’t be part of the nightly backups.

What in the world is That?!?

Last friday, I sent out a
message asking for suggestions on things to include in my “What in
the world is That?” chapter of my tutorial on
developing with Gnome. No one responded for three days, so I
started thinking that no one would. I was a little disappointed. But
then it turned into a fairly active thread. While some of the
suggestions were things that were either already in my tutorial or
that I had planned on putting into my tutorial (although not all in
that chapter), there were some cool suggestions and ideas that came
out of it.

On a related note, I’ve used all kinds of devious underhanded tricks
to try to get people to review my tutorial. Such as asking them to
review my tutorial. Okay, so maybe that’s not so devious. I’ve had a
few people state that they would. pbor (Paolo Borelli) is
the first (and only so far) to make significant comments about more
than a single section. He provided some great ideas for things to add
which was really cool. Hopefully, others will review it as well and
continue helping to transform it from a beginner’s project into a
rocking guide.