Archive for November, 2009

Making Valuable Connections

I realize this post’s content will be a little different than the rest, but I think it’s important for technical writers.  As much as we’d like to believe it, we don’t get careers solely by merit–we need connections.  Sure, you need to know what you’re doing, but you’ll never get the chance to demonstrate your knowledge if you don’t know anyone.  Although it isn’t necessary, it can be very helpful to join the STC (Society for Technical Communication).  There are chapters in every state, and your participation in them goes a long way.  The greater your participation in the STC, the greater your success rate in making connections with other technical writers.  If you happen to apply for a job where one of your connections works, you have an in.  You have a specialized in.  You don’t just know the secretary or the receptionist; you know a technical writer–someone from your chosen line of work–and that’s invaluable.

It’s also convenient that the STC still holds merit of its own.  If you’re evenly qualified with someone else for a position, but you’re a member of the STC, that may be enough to put your over the edge.  I think the major reason why that’s the case is it shows you’re serious about your work and willing to do extra outside the workplace.


John R Larsen

Categories: General

Trigger Happy with Hyperlinks, Part Two

As promised, this post will deal with the technology associated with technical writing.  I said we include things because we can, and that’s true.  Technical communication integrates technology with language.  There are some emerging programs that will allow you to enhance your work, two of which are:

1.  Dita markup language

2.  Google Wave

I’ve already spoken about Dita in my post, So How Do You Get Ahead?  I haven’t spoken about Google Wave.

Google Wave is an easy application that allows you to embed wave files in Confluence wiki pages.  Once you’ve downloaded it, you only need to follow two steps:

1.  Edit an existing wiki or create your own.

2.  Add a {wave} macro.  You can do that by typing the wiki markup or by using the macro browser in Confluence.  Here’s the form: {wave:url=my.wave.url}.

Play with Google Wave a little and see how it works!

I’d like to acknowledge that my main source of information for this blog as Sarah Maddox, a technical writer in Sydney, Australia.  You can visit her blog at


John R Larsen

Categories: Technology, Uncategorized

Trigger Happy with Hyperlinks, Part One

Technical communication is beginning to lean pretty heavily on interactivity (i.e, electronic technical documents are beginning to be interactive for their users).  I think there are a few major reasons for that trend:

1.  People retain more information when the document is interactive.

2.  An interactive document keeps the attention of its readers.

3.  We have the technology.

Even if we think the content is very interesting, we could watch an entire presentation without remembering a thing.  If we were given a PowerPoint presentation that required its reader to participate (e.g., one that made us use the tool we were being taught about), we’d be much more likely to remember something.  And since we’d be participating, our chances of losing interest drop dramatically.  All technical communication is about gearing your work to your audience, and making your work interactive is a fine way to do that.

There are a lot of things we do because, frankly put, we can.  That’s where the technology comes in.  We include video links, hyperlinks, wave files, and work from Captivate because we can.  What we do changes with the technology.  We’ll talk more about the technology in the next post.


John R Larsen

Categories: Uncategorized

Why Read when You Can Look?

This post is a kind of continuation of the last post.  It deals with manual writing, but it isn’t directed towards writing style.  Instead I’ll be addressing picture usage.

People don’t read anymore; they look.  Even if you were dealing with the same amount of text, your audience will be more drawn to the manual with pictures.  Don’t take this the wrong way–your content still has to be good.  Adding pictures makes it more effective.  Let’s say you’re writing a small section on how to assemble a puzzle.  You’ll probably say something about placing two pieces together and seeing if one edge can fit into another.  We can break that into three steps:

1.  Take two puzzle pieces.

2.  Place them side-by-side.

3.  See if the edges of each piece can fit into each other.

Those steps are still correct, but your audience will understand them much better if you have a simple picture for each step (depicting the action).


John R Larsen

Categories: Interactivity

If Manual is Boring, User Should?

Some of us, as technical writers, find ourselves writing manuals.  We all know nobody leaps out of their chair and says “oh boy!” when s/he sees a manual, so our work is to make it as easy-and-efficient as possible.  Doing that typically means forgetting everything your high school English teachers taught you.  Using big words you don’t understand really doesn’t get the job done–not in an essay, and definitely not in a manual.  I think we can help our audience a great deal by making our manuals simple.  Let’s look at a sample sentence:

If manual is boring, user should disregard all information.

A lot of people think passive voice, or noun style, is accepted as the professional tone.  That’s a mistake.  Phrasing things in active voice can save your audience a lot of confusion.  Let’s reword our sample sentence:

Disregard all information if the manual’s boring.

We never addressed an ambiguous person named User, we didn’t start with an adverbial clause, and we didn’t use passive voice.  The result was a crisp, clear sentence.

Till next time,

John R Larsen

Categories: General