Blog Archives

A technical writer in Sydney – and some trees

Julie Norris had a great idea this week. She has created a YouTube channel specifically for the #tcchat Twitter chat group, and she’s uploaded a video of herself and her corner of the world. Now she’s inviting us to do the same. What a lovely idea, thanks Julie!

So I’ve spent the last few days making a video and uploading it to YouTube. To cut a long story short, here’s the video. As Julie suggested, the video introduces me as a technical writer working in Sydney, and shows you a bit about my surroundings:

I think it’s a cool idea that will help to bring far-flung technical writers closer together, especially those of us who take part in the #tcchat Twitter chat group.

The long story

It took many, many tries to get this far. I have to confess that the air turned a delicate blue hue at times. Why oh why are movie formats so finicky, fussy and frustrating? ;)

I first read Julie’s post when I was on the bus on the way to work. Unsurprisingly, I did not have my camera with me. I did, however, have my sparkling new iPhone 4, which does movies. Cool. I made a cute movie of the Sydney Harbour Bridge through the bus window, and of the building where I work. On the way home, I filmed a Paperbark tree flapping in the breeze and a Sydney Red Gum glowing in the gentle afternoon light.

The next day I sallied forth with my “real” camera and took some more movies.

Then I attempted to splice them together. Disaster. I tried free software and trial versions of expensive software. Suffice it to say: Nothing works perfectly.

So in the end, I’ve decided to use the software that came with my Canon camera. It’s pretty good, but it is not able to merge the movie files made by the iPhone. It gets the picture OK, but no sound.

Oh, and I’m fond of Australian trees. You’ve probably noticed there are a couple in the movie above. :)

My trees and this blog are one year old

In August last year, I planted two trees at about the same time as I started this blog. Now the trees and this blog are just over a year old. A good opportunity for some stats :)

ffeathers

WordPress says that ffeathers has:

  • 62 posts
  • 184 comments
  • 184 tags (hmm, interesting but meaningless coincidence)
  • 17,216 total views
  • 7,584 blocked spam comments (thank you Akismet)

The most popular post is The agile technical writer with 1,247 views.

Today, someone found ffeathers by Googling for:

“your mouse has moved” error

I hope you found what you were looking for :)

Prickly Paperbark

Yesterday, another person came here searching for:

paperbark tree information on growth

So in your honour, here’s some idea of what a Paperbark tree does in a year.

The Prickly Paperbark was a tube, about 40cm high, when I planted it in August last year. Now it’s nearly 2 metres high and quite robust. (It needs to be robust, to survive the onslaught of weeds, floods, cold and heat that our garden inflicts upon it.)

Prickly Paperbark a year ago, at 40cm

Prickly Paperbark a year ago, at 40cm

Prickly Paperbark now, at 198cm

Prickly Paperbark now, at 198cm

It has a very pretty trunk and bark already. The diameter of the trunk is almost 3cm at its thickest part.

Prickly Paperbark close-up

Prickly Paperbark close-up

Old Man Banksia

The Banksia has not grown much since I last measured it in April this year. It’s approximately one metre tall, and battling an ever-changing environment. Since I planted it, a couple of tree ferns have muscled in on the territory.

Old Man Banksia last year, at 17cm

Old Man Banksia last year, at 17cm

Old Man Banksia now, at approx 1 metre

Old Man Banksia now, at approx 1 metre

Still, it is putting up a gallant fight. Its trunk is almost 2cm in diameter and it always has a lot of new growth, although much of it goes sideways in an attempt to find the sun.

Old Man Banksia close-up

Old Man Banksia close-up

As well as my two favourites, we planted around 20 native trees and shrubs last year. Spring has sprung, and we’ll be shopping for more soon. Death to all agapanthus ;)

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” :)

My Prickly Paperbark tree

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 ;)

My Prickly Paperbark tree

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

My Prickly Paperbark tree

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.

Follow

Get every new post delivered to your Inbox.

Join 1,447 other followers

%d bloggers like this: