I just wrote a short tutorial on how to embed SVG in Mallard. Because Mallard is designed well, you can easily mix other XML vocabularies into it. That means that simple SVG in Mallard wasn’t a good enough challenge. So I made it so that embedded SVG can use Mallard’s linking mechanism. With a bit more work, we could probably even dynamically generate text labels in SVG from Mallard page titles. And that could be the framework for some nice charts and diagrams.

The essence of technical writing is explaining. Whether you’re writing an introductory tutorial or a massive reference manual, your goal is always to explain something to the reader. It follows that to be a better writer, you should be a better explainer. And as with any skill, you get better with practice.

Take opportunities to explain things to people. Remember that guy at the gas station asking for directions? Take a few minutes out of your day to help him. Think about his frame of reference. Will he be able to recognize local landmarks? Does he know which way North is? Think about the different ways he could accomplish his task. The route you would take isn’t necessarily the best route to send him on.

Explaining things to people will help you understand how others might think. You get used to the things you know, and it’s sometimes hard to articulate everything to somebody else. You might leave out steps that seem obvious to you. The more you explain things, the better you will become at anticipating gaps in your explanations.

If a colleague asks you to explain your work or your decisions, do it. Don’t treat it like a challenge or a distraction. Explaining will help you better understand the subject: the best way to learn is to teach. And it will help you create things that make sense to other people.

Try taking things a step further and writing instructions for things in life. Sure, it could be about complicated technology, like programming your VCR. But you can write instructions for low-tech things too. If you like to cook, write instructions for one of your favorite meals. Then ask somebody else to cook from your instructions. Remember that terms that are familiar to you might be lost on your reader. Does your reader know the difference between simmer and sauté?

By explaining things through instructions, you practice explaining without immediate feedback. Face-to-face instruction is wonderful, but it’s not a luxury you have when writing documentation. You have to take your skills in explaining things and put them to use in an environment where you can’t see confused facial expressions or answer questions.

Make a habit of explaining better in everyday life, and you will find you’re more able to create things that other people actually understand.

Silke and I have an old Archos DVR.  I’ve never been extremely happy with this device, but it gets the job done.  Last night I recorded the Lost season premiere.  Instead of scheduling a recording, like I usually do, I just started a recording immediately, expecting it to keep recording until I hit Stop.  Instead, it stopped on its own after an hour and fifteen minutes.

Wanting to know why, I checked the built-in manual.  The Archos manual is a 79-page PDF file that you view on-screen.  You can view about half a page at once, and the scrolling is slow.  It doesn’t automatically advance to the next page when you scroll past the bottom; it takes three button presses to do that.  And it takes it about three seconds to render a page.

No matter how good the content is (and, to their credit, I did find the answer), this is a complete failure of a delivery mechanism.  This got me thinking in general about best practices for help embedded in set-top boxes, appliances, mobile devices, and other systems with limited interaction or screen space.

I’m sure it’s no surprise that I think the best thing in this case would be topic-oriented help.  A device like this almost certainly needs a printed setup manual, but beyond that, people are mostly going to look for specific answers.  And they’ll lose any printed material you give them, so the best place to put the help is on the device.

Devices like this present some unique challenges.  Things we take for granted in the desktop world aren’t necessarily so elsewhere.  Any UX people with experience in mobile or embedded devices could probably talk my ear off about this.  (Please do, by the way.)  So what kinds of problems are there?

• Disk space is often limited.  My Archos has a hefty 80GB hard drive.  That’s huge by embedded standards, but tiny by desktop standards.  Help files take up space, especially once you start adding figures and screenshots.
• Screen space is limited.  Applications usually run fullscreen, and that would include your help viewer.  The fact that you can’t view the help and the helped application side by side can really affect the way you write.
• Another effect of limited screen space is that there often isn’t enough space to put lots of context-sensitive help buttons in the UI.
• Interaction is cumbersome.  Mobile devices almost always use a touch interface these days, and for a lot of things that’s very powerful.  But set-top devices that use your TV usually just use a rocker on a remote.  That’s a terrible substitute for a mouse.  And text entry without a keyboard is never fun.

I don’t buy into the notion that desktop systems as we know them today will die any time soon.  But it’s clear we’re going to see more and more of these sorts of devices in our daily lives.  So I’m very interested in how we can provide better user assistance in this area.

It looks like there are a couple of related talks at the upcoming WritersUA Conference.  Unfortunately, I won’t be able to attend one of them because I’ll be presenting Mallard in the peer showcase.

The Gnome documentation team will hold a team meeting this Sunday the 10th at 18:00 UTC. We will discuss Mallard page templates, the accessibility documentation, and plans for projectmallard.org, plus anything else that people want to discuss.  Feel free to add to the agenda on the wiki.

Please plan to attend, whether you’re an experienced documentation person or not.  The documentation team is a great way to get involved with Gnome, and we have a lot of exciting things happening right now.

(Copied from the documentation team blog.)

This is a fun piece of shell I thought I’d share. For gnome-doc-tool, I need to convert file paths into URLs and back. That means urlencoding and urldecoding them. I searched around and found a few solutions, mostly using a few dozen lines of awk. Now, I’ve been known to write some crazy stuff in awk (like an RNG compact syntax parser), but this seemed like too much work for a simple problem.

Then I remembered printf(1). It can do all the work of converting characters into hex byte representations and back. All you need to write is a loop to iterate over the string.

# This is important to make sure string manipulation is handled
# byte-by-byte.
export LANG=C

urlencode() {
arg="$1"
i="0"
while [ "$i" -lt ${#arg} ]; do
c=${arg:$i:1}
if echo "$c" | grep -q '[a-zA-Z/:_\.\-]'; then
echo -n "$c"
else
echo -n "%"
printf "%X" "'$c'"
fi
i=$((i+1))
done
}

urldecode() {
arg="$1"
i="0"
while [ "$i" -lt ${#arg} ]; do
c0=${arg:$i:1}
if [ "x$c0" = "x%" ]; then
c1=${arg:$((i+1)):1}
c2=${arg:$((i+2)):1}
printf "\x$c1$c2"
i=$((i+3))
else
echo -n "$c0"
i=$((i+1))
fi
done
}

That’s it. If you use these functions on potentially garbage input, you might want to add some error checking. In particular, the decoder should probably check that there are two more characters, and that they are valid hex digits.

Last week, eight of us converged on Chicago for a Gnome marketing hackfest. Thanks to Google and Novell for thier generous sponsorship. There are other blogs posts about the event, including posts from Brian Cameron, Paul Cutler, and two posts from Jason “The Chronicler” Clinton.

Unfortunately, I had to leave early on the second day, which seems to be when the dust settled and some real work got done. But we had some great discussions on day one. Others have recapped most of our discussions well, but one thing they haven’t talked about is our discussions about mentoring.

I’ve spent the last eight years trying to build and foster a community of documentation writers, most of whom are not professionals. So I’m particularly interested in how the marketing team can mentor new team members who, like me, don’t really know anything about marketing.

My one contribution was a lesson I’ve learned over the years: Give new contributors achievable and concrete tasks. If you tell them to pick something and do it, they usually won’t.

Stormy, Denise, and I continued this conversation at the bar on Tuesday night. One of my big questions was “What do people need to learn?” If you have no background on something, it might not just be the answers you’re lacking; you might not even know what questions to ask. Not only do I not know things about marketing. I don’t know what I don’t know about marketing.

Stormy and Denise rattled a dozen things off, most of which I’ve already forgotten. (There’s a reason I carry a notebook everywhere. I don’t know why I didn’t take it to the bar.)

So how do we pass knowledge like this along? Sure, we could braindump into a wiki. And somebody who’s skilled at content organization could turn it from a braindump into something useful. But it’s actually really hard to write down everything you know about a subject. The good nuggets of wisdom are things you don’t think to mention until the right situation arises. Real life experience matters.

I’m curious what others have found helpful in bringing new contributors up to speed. This isn’t marketing-specific. It happens in any community where many members aren’t professionally trained in what they’re doing. (And I realize I’m asking about those very good nuggets of wisdom about community mentoring that you don’t think to mention.)