Making Content Effective, Part One

I think the first way to make content effective is using an honest tone.  I don’t mean you have to fight to have your own unique voice, but I do mean you need to use conversational speech.  In most of my blog posts, I’ve tried to keep a professional tone using regular speech.  Here’s what that will accomplish: the people reading your content won’t feel like they’re being taught by a robot.  No one wants to read a boring, generic textbook because each sentence is a paragraph long and you could count on one hand the number of common words each sentence uses.  People want to read things they can understand the first time through, and that’s what you offer them with a human voice.

Another big seller for engaging writing is using active voice instead of passive voice.  Take a look at this example:

1.  (Active)  I visited the store and bought some apples.

2.  (Passive)  The store was visited and apples were bought.

Passive voice really seems to generate the boring textbook feeling.  Active voice generates the feeling that someone’s talking to you.  Active voice sells because it makes the reader feel like he’s part of a conversation, and one at his or her level.

Categories: Interactivity

Catering to the Audience

One of the most important things we do as technical writers is cater to our audience.  A good example of what I’m talking about is the online textbook I’m working on.  I’m part of a group assigned to cover Adobe Captivate.  Since the textbook is going to be written for college students (who we know are much more inclined to skim rather than do in-depth reading), my group thought we should have less text and more interactivity.  So far it’s been a success.

Your project won’t accomplish much of anything if you forget your audience.  For the vast majority, less text and more interactivity is a winner.  But if you have an academic who’d rather read ten straight pages of text, give it to him or her.  The job of a technical writer is to produce what you’re asked to produce in the most effective, specific-to-the-audience way.  That, of course, begs the question: how do I make my content productive?  I’ll address that in my next post.

Categories: General

Single Source vs. Dynamic Source

I recently became aware of a conversation among technical writers: single vs. dynamic source.  Tom Johnson and Michael Hiatt cover the topic at length, and pretty soon a podcast of the two interviewing will exist.  My goal is to expose you to the discussion.

Single sourcing means you create all your content in one place (e.g. in Flare or RoboHelp), publish the finished product, and go back periodically to update it. That’s worked for a long time, but since the world changes, so do our methods.  Now that the world is so connected, something more along the lines of dynamic sourcing is possible.  I say “more along the lines of dynamic sourcing” because there isn’t a formal system for that quite yet.

Dynamic sourcing will take over because it makes it easier to address all of the issues that arise with any given program. The term, dynamic sourcing, means your finished product is always changing (and it’s always changing because anyone can contribute to it).  Instead of having one person discover all of the issues associated with the product, several people can contribute their ideas to better it.  In short, dynamic sourcing will take over because of the “two heads are better than one” principle.

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