The Gist

Friends, hackers, writers: It is with a heavy heart that I stand before you on this momentous occasion to announce the dissolution of the Gnome Documentation Project. Since our humble beginnings under our Founding Father, Dave Mason, our team has been charged with the arduous task of providing complete documentation for the entire Gnome desktop. As the desktop has grown, so too have our responsibilities.

It is clear now that no team of meer humans can hope to accomplish this majestic goal. It is clear that we need something superior to humans. It is clear that we need Python. On this day, the venerable Dave Malcolm has shown us a new way of producing documentation. He has provided for us the tool to do that which we could not do alone. He has shed light upon our dark path, that we may now see that it is not a path meant for the mortal soul.

Through the years, we have developed a camaraderie among our disparate team. Friendships blossomed and new loves bloomed. We have become more than a team. We have become brothers and sisters united in a common cause. We have become a family. But today I must ask you all to lay down your pens for the greater good. Return to your lives, and remember always the days we had together. Godspeed to you all.

</humor>

I just finished reading Federico’s Making GNOME Fast slides. Great stuff, honestly. But I predict that, in one year’s time, these slides will be lost to all but Federico and Google. Presentations are wonderful. They get the word out to large groups of people at once. They get people excited. They’re effective in the short term.

For the long term, our information needs permanence. We need to encourage people to write stand-alone documents like “Making Programs Fast”. Then we need to put them somewhere. Here’s the idea:

1. Somebody create library.gnome.org already.
2. Make user documentation not suck. See Project Mallard.
3. For every library in our stack, have a complete API reference as well as good high-level documentation.
4. Write a core set of developer guides.
5. Put information like this into stand-alone documents.
6. Put it all on library.gnome.org.

A good rule of thumb is that documentation should be definitive. If somebody wants some information, point that person to the place in the documentation where it’s provided. Is the information not in the documentation? Go update the documentation, then point the person to it.

Project Mallard

In which we disassemble the help system, rethink how we present help
to the user, and leave our practices laying in ruins. In which we rise
from the ashes of a long-dead but still-breathing behemoth. In which
we lay the foundations of tommorow and dream of the future.

Garrett and Tuomas:
Maybe there is too much icon noise. But I certainly don’t think a unilateral remove-all-button-icons approach is the best solution. Icons do have an advantage in that they are quickly recognizable once learned. I can spot a Save icon in a widget soup much faster than I could scan for the word Save.

I don’t think the best way forward is adding more rectangles with text. See, for example, our file chooser and Apple’s:

GTK+ File Open Dialog

Mac File Save Dialog

Ours looks boxy with all those icon+text buttons. And just removing the icons wouldn’t make it any less boxy. It’ll just be boxy and texty. What you’ll notice about Mac dialogs is that they’re not afraid to have icon-only buttons.

Without button icons, our Help buttons will look like KDE’s:

KDE Help Button

Apple just uses a cute ? button for Help:

Mac Help Button

(I have no idea why the callout calls it a Back button.) And Windows has a ? button in the titlebar:

Window Help Button

Notice that the KDE dialog also had the ? button in the titlebar. We could go a long way towards being less boxy by having specialized buttons without text. See, for example, the Add/Remove button pair on the Mac:

Mac Add/Remove Buttons

If we had a GtkHelpButton (yeah, all right, I talk about Help buttons a lot), it could render as a stylized button with nothing but the life saver icon, maybe desaturated a little. And on Windows it could still be rendered as a regular text button with “_Help”. Better still, if window/dialog APIs have a high-level add_help sort of function, GTK+ could just use the titlebar button on Windows.

Point being, just removing button icons doesn’t make our interfaces always look better. We ought to step back and look at our designs and some of the common buttons, get some good designers (that’s you guys!) to mock up something that doesn’t fill the screen with boxes, and then figure out how to work that into our development process.

The vacation is over. Yesterday I drove Silke to Chicago (well, Arlington Heights), and today she started her internship. And since Ryan is off in Canada for a week, my house is very quiet right now. Disturbingly so. This can only mean I need more CDs.

In semi-related news, I’ll very soon have to start doing real work. Like, the kind that puts money in my checking account. My days of dancing till dawn every night are over. For now, at least.

Right now, nine über-cool people have joined the all-new
gnome-doc-devel-list.
We have exciting discussions about yelp and gnome-doc-utils. Really, very exciting. Anybody interested in being my personal hero should join the fun.

Much thanks to Ross for sending
me two CDs from my wishlist.
CD the first was
All We Have Is Now by Anonymous.
(That’s the name of the band. The music wasn’t created by a collaborative
system of cowards using peer moderation.) It’s a solid album, and they’re
clearly talented musicians, but I just didn’t get into it as much as I’d
thought I would. But then, my tastes are always in flux. I very well might
return to this CD in two months and love it.

CD the second was Rise Above
by Boogiehawg. True to the description, this is a powerful Modern Funk album.
Their Funk is vaguely like Dag, but with a powerful, jazzy horn section (as
Funk was meant to be played). Occasionally Urban, occasionally Latin, and
occasionally Jazzy, this is one of the finer Funk albums on my shelf.

I know there’s a lot of photo geeks in Gnome land, so I’m trolling here for
camera recommendations. I have only two requirements: it has to be small
enough to fit in my pocket, and it has to be good for low-light motion shots.
As for pockets, keep in mind that I have a
Neuros, and that beast manages to
fit in my pocket. Mostly, it can’t have a lens that sticks out. And as for
low-light motion shots,
here’s
a picture that should have been awesome, but was thwarted by a slow
shutter and my lack of experience.

Last night, there was a Groovatron
concert here in Champaign. Those who know me well may know that Groovatron
is one of my favorite jam bands. Their shows just kick ass. But I didn’t
go to the concert. Why? Dancing, that’s why.

This is what my schedule looks like right now:

Monday

9:15–whenever, dance practice with the Dancing Illini

Tuesday

9:30–10:45, Nightclub Two-Step and New York Hustle lessons
10:45–12:00, Salsa practice

Wednesday

8:30–10:00, Tango lessons

Thursday

8:00–9:15, Swing lessons
9:30–10:45, Salsa and Cha-Cha lessons

Friday

5:15–6:30, Salsa lessons
11:00–2:00, Salsa night at the Regent

In addition to all that, I’m going to a weekend-long hustle workshop
in Chicago tomorrow. I think I might be insane, but it’s a good kind
of insanity.

I’m looking for recommendations for books similar to
The
Elements of Typographic Style and
The
Chicago Manual of Style, but for other languages and writing systems. I’m
particularly interested in the typographic and writing style conventions of
non-Western languages, although there’s still plenty of variation in Western
languages that I’m not familiar with. Bonus points if I can get it translated
to English, but that’s not necessary.

Hey, I’ll even give you a
vote
if you buy it for me.