ffeathers — a technical writer’s blog

As most of you know by now, I am a technical writer at Atlassian. Each member of our technical writing team is responsible for documenting specific products. At the moment, these are mine:

Confluence is kind of: “Here I am - look at my buttons!” Crowd is the strong silent type: “I’m working away in the background, taking care of stuff for you. You won’t see me until you need me.” FishEye’s effortless charm hides a manic cleverness: “Here’s looking at you babe.“ Crucible offers with a nonchalant air: “Do you want to talk about it?“

When it comes to wikis, a good-looking GUI is really important. That’s GUI, not ‘guy’ - though a handsome man never goes amiss. You need to get intimate with your wiki. Every click should give a frisson of satisfaction. Every new page should look awesome on first save. It’s like a good first date. You want to want to come back for more. Delayed gratification is not what you’re after. Otherwise, you’d write the code yourself, in all those xxxML varieties, right?

So I’m really pleased that Confluence 2.6 is here. It’s been a long time coming, and it’s my first big release since I joined Atlassian. So I’m kind of fond of it. It comes with a new theme, more pictures dotted about, and a friendly style. Some people think it’s ugly, but I’m ready to go to bat on that one.

I had a lot of fun devising a new format for the release notes, with much input from other Atlassians. That’s the way things work in the company. You put up an idea, and everyone throws comments at it. After a bit, the final result emerges. Take a look at the new format of the release notes, and let us know what you think.

Some people have made Confluence their own by metagrobolising the look and feel.

Here are some pretty cool sites powered by Confluence: Toxipedia, CustomWare and thesarvo.

Are other wikis sexier than Confluence? And how about Microsoft’s SharePoint - is it pretty or friendly? Let me know what you think…

There’s a mess of traffic that happens in the afternoon rush, while we are squeezed out of the city, over the Sydney Harbour bridge and onto the freeway. Sydney-siders will know what I’m talking about. It’s dusk, people are tired, and everyone in the far left of the zillion-laned freeway suddenly needs to swap places with everyone on the far right. Things tend to move fast and moods are on a hair trigger. There’s not much time for reading.

Is this the right time and place to put a big flashing yellow sign, demanding by its very big-flashing-yellowness to be read, that says:

HORSE TRANSPORT PROHIBITED.

HEAVY PENALTIES APPLY.

I looked wildly around for the hapless horse-drawn carriage that had tripped some hidden camera and so triggered this dire warning. My naive reaction lasted only a second or so, before I realised its absurdity. But I remained puzzled. Luckily, I was on a bus. But there were tired, distracted motorists zooming all round, presumably undergoing equal puzzlement.

So why has this sign been forcing itself upon Sydney’s motorists for the last week? For those motorists who stick around long enough to read the sequel (and so risk a bash on the bumper from the equally puzzled person behind) an explanation follows:

EQUINE FLU ALERT.

HORSE TRANSPORT PROHIBITED.

Ah, so that’s it. But, dear RTA, please take a leaf from a technical writer’s handbook and consider your:

• Audience. Do I and the other commuters really need to know what you’re telling us? Correct me if I’m wrong, but I don’t think the freeway between Harbour Bridge and the Falcon Street offramp is a favourite haunt of the horse transport fraternity.
• Timing: Do we need to know it now? Perhaps rush-hour should be left for rushing rather than for a leisurely reading session.
• Emphasis: Is it really so urgent that it needs to be big and flashing and yellow?
• Medium: Why should this be a road sign at all? Perhaps radio announcements, TV coverage and newspapers would have done the trick.
• Content: If the message does have to be out there, make it short and informative rather than threatening and confusing. The second notice shown above would have been enough. If I’d seen that one first, I’d have known what it meant. And I didn’t need the first one at all.

After all, if I were moving a horse around I’d probably have to keep moving it for at least a while, rather than coming to a standstill in the middle of the freeway so as to avoid those heavy penalties.

(For non-Sydney-siders: ‘RTA’ is the Road Traffic Authority - which usually does a very good job but is in my opinion a bit too liberal with its signs.)

Yesterday the chubby two-foot-high Buddha in our living room started plinking. Every five minutes or so, we’d hear this gentle, unassuming ‘plink’ from his quiet corner. Closer investigation revealed that the ceiling has developed a slow leak directly over the Buddha’s right arm. We’ll have to fix it some time, but no worries. It only happens when it rains.

Inevitably, this experience leads me to some philosophical meanderings. Why is the Buddha plinking now, at this particular moment in time? Yesterday was Friday 7 September. Could this be a gentle comment on the APEC goings-on in Sydney? A subtle, enlightened type of protest, to show up the Chasers‘ more obvious antics? Or is it pure coincidence? Do coincidences even happen?

I’m not a Buddhist. Philosophically, I’m a mix-and-match kind of girl. But one of Buddhism’s central tenets appeals to me:

At the centre of everything is nothing.

This is a strangely comforting idea. It’s worth doing a bit of meditation in search of that nothingness. It helps when waiting for the E66 that never came, or ironing clothes that are wrinkly by force of nature and destiny (ironing has to be the most futile occupation ever) or undergoing other more troublesome vagaries of life. Hey, it’s freakishly fortunate that I exist to have this experience at all. And other creatures around me are similarly amazing and lucky to have made it this far.

‘Nothing really matters to me’. You can take that two ways.

What does all this have to do with technical writing? Very little. Almost nothing, in fact. Close enough to matter.

When you’re writing a document, and you really get in the zone - that’s much like losing the self. When you surface and notice what’s going on around you with sudden clarity, that’s mindfulness. When you’ve spent hours writing glorious prose and then have to hone it down to the bare bones, that’s an exercise in humility. (Select a shoe size. Click ‘Submit’. Click ‘OK’ to confirm your selection.) When you wonder why you’re telling people how to do something so utterly unrelated to real life, that’s when it helps to know that nothing really matters. And so everything really matters.

My mum and dad have recently given me a copy of Karen Armstrong’s latest book, The great Transformation. The World in the Time of Buddha, Socrates, Confucius and Jeremiah. Thanks guys! I’m looking forward to digging into it. A while ago, I read Karen Armstrong’s Buddha. I think she did a good job there, with a very hard subject.

The hero of Robert Pirsig’s Zen and the Art of Motorcycle Maintenance is a technical writer. Here’s a passage from the book that stands out for me:

“What I wanted to say,” I finally get in, “is that I’ve a set of instructions at home which open up great realms for the improvement of technical writing. They begin, ‘Assembly of Japanese bicycle require great peace of mind.’”

A leaking roof is not the end of the world. It ain’t over when the fat Buddha pings.

Garden zen