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” 🙂


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 5 July 2008, in atlassian, Confluence, language, technical writing, trees and tagged , , , , , , , , , , , , , , , , , , . Bookmark the permalink. 5 Comments.

  1. Rachel Peters

    “Sarah is eat a chocolate” makes my brain hurt. You make great points. I think sometimes it’s good to cause LANs if it brings more attention to an important point. Kind of like using a fragment just to mix things up.

    I agree language is ever changing over time, audience, and place. And I really like your idea of “a smooth ride through the text.” As a new technical writer, I often felt compelled to write strict, super-concise text. But as I’ve written more and listened more to feedback, I see that conversational writing goes a long ways too. Writing for a software company, I don’t get many options to be conversational, but I still sneak that style in when I think it will help users.

  2. Hallo Rachel,

    Cool comment! I really like the idea of zapping someone with a LAN, or even an N400, to wake them up and make a point. Up with fragments 😉

    Your point about conversational style is a good one too. We’re trying to help people understand something. We can choose simple, non-intrusive language, peppered with the odd surprise a la Haydn, and a bit of friendly comment here and there too.

  3. The correction of source text is often an important part of a technical writer’s work. However, to be able to re-work text, we must understand what the writer intended to mean. The knowledge elicitation skills that technical writers have are as important as their language skills.

    Simplified Technical English, or controlled language in general, can be a huge benefit to technical writers. For example, I once documented the diary functions in a software program. I wrote ‘dairy’. I did not see the error. The spell checker did not flag the error (how could it?). The customer did not see the error. If I had used a controlled vocabulary, my error would have been clear.

  4. Hallo Mike
    Great point! I hadn’t considered that aspect of STE before. I’d thought of STE or controlled vocabularies as an aid to people whose native language is different to the one used in the manual. It would be very useful to pick up terms which don’t belong or aren’t immediately recognisable in the context.

  1. Pingback: Is it OK to say PDFs « ffeathers — a technical writer’s blog

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: