The Gist

I was asked for the script I used to count element usage in our DocBook files, as posted here yesterday. I’ve got to be honest. I wrote it in Mathematica. Why? Well, I thought through the problem in my head, and I thought to myself “Golly, the Split function would be handy here.”

But hey, it’s not all that hard with sh, given the right tools. So I wrote up the script again in something everybody could use. It’s a simple sh script, using the XMLStarlet utility. Don’t have XMLStarlet on your machine yet? Go get it. Get it now. XMLStarlet is a godsend for any *nix geeks doing XML stuff. Learn it, use it, love it.

Here’s the script in plain ol’ sh:

#!/bin/sh

rm -rf ALL && touch ALL;
rm -rf COUNT && touch COUNT;

for dir in /usr/share/gnome/help/*; do
    name=`echo $dir | sed -e 's/.*\///'`;
    doc=$dir"/C/"$name".xml";

    xmllint --xinclude $doc \
	| xml sel -t -m "//*" -v "name(.)" -n - \
	| grep -v '^$' >> ALL;
done;

for el in `sort -u ALL`; do
    echo -n "$el " >> COUNT;
    grep -c $el ALL >> COUNT;
done;

sort -k2 -rn COUNT >> COUNT.tmp && mv COUNT.tmp COUNT

Following Federico’s suggestion, I whipped up a script to see how often we use which DocBook elements in our help files. The top four are para (10499), entry (3415), listitem (3114), title (1948). None of these came as a surprise to me. Here’s some interesting data points:

The rundown of how often the basic sectioning elements are used: sect2 (1201), sect1 (502), sect3 (205), section (8), sect4 (2). We have very few documents using the section element. In general, I favor using section, but the numbered ones do provide more information with this script (not that it would be hard to write another depth-checking script). Since sect2 is used more than twice as often as sect1, it seems two-level section is common. Deeper levels seem rather uncommon, although three-level isn’t rare.

Articles (70) and books (4), right about what I expected.

On basic inline markup: guilabel (1858), application (1527), keycap (1032), guimenuitem (792), guibutton (744), filename (702), guimenu (647), menuchoice (605), literal (281), keycombo (214), phrase (206), replaceable (170), command (140), guisubmenu (134), userinput (109), and stuff that didn’t manage to hit 100. Those in the know will know that guilabel (1858) is used as a catch-all for most things on the screen. Its high usage amuses me, because it means DocBook’s various gui* elements can’t manage to catch everything. I think it should give up. Note that menuchoice (605) is used far more often than keycombo (134). I was actually surprised that userinput (109) was used as often as it was. I’ll have to take a look at where it’s being used.

On lists: listitem (3114), varlistentry (1135), itemizedlist (309), variablelist (276), orderedlist (267), simplelist (3). I didn’t expect a high turnout from simplelist (3). Since listitem (3114) is used in most lists (just as li is used in both ol and ul in HTML), its number wasn’t surprising. There’s not a huge difference in numbers between the three common list types.

The titleabbrev element was used only once. I’ll bet I’m the one that used it, too.

We used indexterm 242 times, a primary term 241 times (huh?), a secondary term 128 times, and a tertiary term only 17 times.

We used the general-purpose synopsis element 123 times. As expected, we didn’t use any of the special-purpose *synopsis elements at all.

Admonition breakdown: note (96), tip (26), caution (6), warning (5), important (1). I still don’t have a clear idea on the difference between caution and warning. I was surprised that important was used only once.

There were 232 imageobject elements, but only 204 textobject elements. That means we have images without accessible text.

Some block elements: figure (188), screenshot (187), informaltable (172), mediaobject (164), screen (68), table (64), literallayout (27), programlisting (13), highlights (13).

Finally, we used just 146 out of DocBook’s 411 elements.

For is it not written in the Book of Gnome:

In the darkest hour of the Documentation Project, there shall come a False Hope of salvation. And the last Fearless Leader of the old ways shall embrace the False Hope, and the eyes of the people shall be blinded to the truth. They shall trust in the False Hope and lay down their pens, and the Project shall lay in ruins.

Though the Serpent speaks in the tongues of men, he is not man, nor shall he deliver man from the darkness. He is a lie, preying on man’s weaknesses and desires. He who believes in the Serpent shall be forever scarred, and shall do good deeds no more.

And the last Fearless Leader, being marked by the lies of the Serpent, shall nevermore lead men in the great Project they knew. Only the benevolence of times past shall resurrect their charge.

Then the trumpets shall sound as Our Once and Future King returns. And he shall return to the people the benevolence and love of times forgotten. And his reign shall last a thousand thousand days.

So was it prophesied, so shall it be.

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.