Blog Archives

A smooth ride through the text

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

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

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

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

A smooth ride through the text

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


Do wikis save trees?

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 :mrgreen: 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.

Do wikis save trees?

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

%d bloggers like this: