ffeathers — a technical writer’s blog

Part of our job as technical writers is to give our readers a smooth ride through the text. And it’s not a small part of the job either. It’s important, even if it means we spend a fair bit of time correcting other people’s writing. Or does that just turn us into glorified copy editors — what do you think?

This isn’t new to most tech writers, but it came to mind again recently when I was making a couple of very small corrections to a page in our Confluence documentation. A reader had added a comment to the page, saying that she had noticed a couple of typos. Thank you Rosie (The comment is still on the page at time of writing this blog post, but it will probably disappear in a couple of weeks.)

Rosie had picked up two spelling mistakes: “serch” and “mutliple”. I myself find the second one particularly bothersome, because my eyes don’t quite believe that they’re seeing it right. So they go back a couple of times just to check that the mistake really is a mistake.

Why is this important?

Because we don’t want to distract our readers from the important stuff just because it’s written funny

OK, so prove it!

It’s easy enough when we’re talking about simple spelling mistakes. “Serch” should obviously be “search”. And “mutliple” is just painful. But what about the more complex aspects of grammar, vocabulary and style?

When you read a sentence like this:

Sarah is eat a chocolate.

you’re hit by a LAN.

And this one:

On the way to work this morning I saw a goldfish swimming around the bus.

gives you an N400 when you read the word “bus”.

A “LAN” (Left Anterior Negativity) is a measurable blip in the electrical impulse which your brain emits when your internal language processor encounters something ungrammatical — like the word “eat” in the first sentence. The blip takes between three and seven tenths of a second to register on an EEG.

An “N400″ blip happens when you encounter a word which doesn’t fit the context - like the word “bus” above. This one takes about four tenths of a second.

This information comes from Steven Pinker’s book, Words and Rules. It was pretty cool to learn that there’s a measurable physical manifestation of that feeling of discomfort I get when a sentence jars.

But what is “correct” English anyway?

I might suffer a LAN zap when you write “Remember to invite Peter and I to your party”. But many people don’t!

(BTW, “Peter and I” is wrong in that sentence, and I’m ready to battle that one out to the end if anyone’s game to take me on )

Or you might get a LAN buzz when I start a sentence with the word “or”. But I think it’s OK.

Why does the tech writer get to decide what’s right and what’s not?

We don’t. Language is a living, changing thing. Different words and constructs will sound good or bad to different people and at different times in history. Consistency is the key. Provided a document or a documentation suite is consistent in its usage of grammar, style and vocabulary, the reader will get that fabled smooth ride.

So which standards do we use? It doesn’t matter all that much, provided you pick a standard that is recognised in your neck of the woods.

At Atlassian, where I work, we use these two guides:

• Style manual for authors, editors and printers (John Wiley & Sons Australia)
• Macquarie Dictionary, Fourth Edition of the Essential Dictionary (University of Sydney)

We’re based in Australia. Our US office has copies of these books too, and we’ve agreed to go with the Australian standard because we’re originally an Ozzie company. I suspect that many Americans think it’s cute

Taking standardisation even further…

Scott from DMN writes about a DocTrain West session he attended, given by Berry Braster and listing the advantages of Simplified Technical English.

A Scribbly Gum tree in my garden

Moving on to scribbles and smoothness of another sort… The Scribbly Gum tree is quite common in this part of Australia. It has a lovely smooth white bark which gleams silver in the wet.

A smooth ride through the text

As you get closer, you notice some weird zigzag lines marring the smooth surface. It’s just as if someone has scribbled on the bark.

A smooth ride through the text

The markings can be quite intricate and almost seem have some meaning which you can’t quite discern.

A smooth ride through the text

But actually, the “drawings” are tunnels dug by the larvae of the Scribbly Bark moth, known less intimately as Ogmograptis scribula.

A smooth ride through the text

I vote that we make the Scribbly Gum the mascot of technical writers. All in favour say “aye”

This is a special edition of the ffeathers blog, to report the spectacular growth of my Prickly Paperbark tree since I last blogged about it approximately a month ago.

On 13 April, the tree was 172 cm. Today it’s 188 cm — grown 16 cm in five weeks! It’s now over 6 foot and taller than I am. I planted it in August last year, so it’s about nine months old.

Alas, it’s not only the Paperbark that has been growing. I spent a couple of hours this morning removing the Asthma Weed and Wandering Dew that had draped themselves all over the tree and its neighbourhood. Don’t gardens ever take a rest period in Sydney?

Just to reassure anyone who might be concerned about the Old Man Banksia I planted at the same time as the Paperbark: It’s doing fine too. It hasn’t grown so spectacularly since my last post a month ago, so it doesn’t warrant a special edition

Here’s a closeup of the trunk, with a peg for perspective:

It’s a great week for technical documentation on a wiki. Confluence 2.8 is out and it includes manual page ordering. The technical writers at Atlassian have been vocal lobbyists for this feature for quite a while. I’m sure that many people who voted for the feature are technical writers too.

When you’re writing a documentation set, the sequence of the pages and chapters is very meaningful. It’s nice… well, many would argue that it’s essential to be able to define a logical page order rather than being stuck with an alphabetical order. Up to now in Confluence, we’ve worked around the problem by manually adding chapter numbers and page numbers, like “1. Introduction”, “2. Installation Guide”, “2.1 System Requirements”, and so on. Now take a look at point 2 in the Confluence 2.8 Release Notes. We can just drag and drop the pages and chapters where we want them. They stay there and the new order is reflected in the PDF outputs and hierarchical page-tree views. Magic.

Here’s the page-ordering feature request on our JIRA issue tracker — it has 174 votes and 87 watchers (i.e. people who want automatic notification of any developments on the issue). The JIRA voting system certainly helped to get this particular feature into Confluence. It was a non-trivial change, and took a fair bit of effort from the development team.

A big hug for the Confluence team on behalf of technical writers everywhere ♥

Other Atlassians think the new version of the wiki is awesome too. See what Fag on FOSS has to say. There were a number of people involved in getting the release out there, and it’s cool that we’re all so pleased with it.

How are my trees doing?

It’s been a while since I ventured to the top of the garden to check up on my two trees. Some of you many have seen my first post about the trees, way back in August last year, when I planted the trees. Now they’ve been in the ground for eight months. They’re about the same age as this blog.

The Old Man Banksia is now 98cm high, grown from 17cm at planting:

The Prickly Paperbark has shot up to 172cm, from 40cm at planting. Its trunk is about the girth of my finger. As you can see, the garden around the Paperbark is a bit of a jungle, but the tree is holding its own:

Do wikis save trees, and do we even want to save trees? Global warming, carbon-trading, green politics — where do wikis fit in, and are they even relevant?

I’ve worked in an office environment for quite a few years. Recently, I’ve started using a wiki to write, review, update and read documents and to share ideas. My desk is definitely more paper-free than ever before, largely due to the use of the wiki.

So my gut-feeling is to say, ‘Hey, wikis save trees!’ Being a tree-hugger and a wiki-hugger both, this feels like a good place to be.

But take a look at this article by Chris Anderson, which seems to prove that my good place is an illusion. Printed documents have a lower carbon footprint than online documents! So even if wikis save trees (which is debatable in itself) perhaps we don’t want to save trees. The paper industry puts them back in the ground, whereas a wiki doesn’t.

Chris Anderson’s article has a very long, heated and interesting comment trail. After reading it, I’d like to take a slightly different tack. He is concentrating on articles which are written once, and then read by many people. Websites are viewer-intensive.

How is a wiki different to a web page?

Many wikis are used for short-term collaboration rather than, or as well as, longer-term information storage. You might put an idea up on a wiki. A number of people would then review it, add their comments, and update the page. At the end of the process, an idea has been formed and is out there in the noosphere. People probably won’t go back to the wiki often to look at that particular idea. You could say the wiki is scribble-intensive.
The key thing is: In the review and refinement process, if we use a wiki then we aren’t passing around and scribbling on pieces of paper. We aren’t even exchanging long and confusing email chains which eventually force you to print them out just to keep track of who said what in reply to whom. Nor are we using Word documents, where the change-tracking is just as confusing Nor even any backs of envelopes or matchboxes.

Instead, the wiki page distills and merges all updates so that it shows the latest aggregation at any one time. And if you need to, you can go back and examine the change history to see who did what.

We’re online anyway. Given that the bad effects of the technology exist whether you use a wiki or some other form of website or computer technology, perhaps wikis are a step in the right direction.

What do you think?

Does anyone have any figures which go to prove this question either way? Maybe someone in the publishing industry has some experience of using a wiki for pre-publication drafting and review. Or perhaps there are some other industry-specific stories out there. Do you have anecdotal evidence, or even some documented statistics?

Ozzie tree shedding its bark

Here’s a tree in our garden. In early summer (that’s December on this side of the world, when I took this picture) the tree chucks all its bark on the ground. The new ’skin’ underneath is a lovely mixture of salmon pinks, oranges and greys.

The story goes that early visitors to Australia were amazed by trees like this, because they shed their bark in summer rather than their leaves in winter.

Sydney Red Gum (Angophora costata) aka smooth-barked apple.

Some words are captivating. Here are a few I’ve come across lately. They’re all related to linguistics. Maybe that’s why they appeal to me. Or maybe it’s just the way they sound. I’d be interested to know if you think these words are cute, and whether it’s because you’re a linguaphile too?

Bahuvrihi — a compound word like ‘lowlife’ or ’sabertooth’, where the meaning of the word is not a type defined by one of its parts. A ’sabertooth’ is a type of tiger, not a type of tooth. A ‘lowlife’ is a type of person, not a type of life. This property is significant, because it affects how we use the word in a sentence. For example, when talking about more than one of these things, we automatically use the regular plural rather than the irregular. So we say ‘I went back in time and saw a lot of sabertooths’ — not ’saberteeth’. And we say ‘lowlifes’, not ‘lowlives’. Compare ‘workman’ (not a bahuvrihi, because a workman is a type of man) with ‘walkman’ (a bahuvrihi). We talk about many ‘workmen’. Can we say, ‘how many walkmen do you have’?

Dvandva – a compound word made of two equally-weighted nouns, like ‘girlfriend’ and ’singer-songwriter’. These words have a similarly intriguing effect on our internal language generator, but let’s not go there

Synechdoche – that’s when you use part of something to refer to its whole. ‘I got me a new set of wheels’ means I bought a car, not just the wheels. When you ‘count heads’, you are counting the number of people, not just their heads.

And my favourite: hapax legomenon — a word or term which is used only once in a particular body of text.

This weekend I’ve been writing some Christmas cards, and struggling as usual to find the right words. Maybe I’ll drop in the odd hapax legomenon to spice things up

Thank you to Kate for lending me Words and Rules, the book in which I found these words. And to Steven Pinker for writing it.

Some tree news:

Here’s a tree recovering from a fire in the Manly Dam reserve:

And here’s a grass tree (Xanthorrhoea) which survived the fire altogether: