Archive for the ‘General’ Category

When Readers Attack 3

I had a little fun with the title; it’s making fun of the old Fox shows usually named something like “When Animals Attack 6.”  I’m finishing a project with a team recreating the content for an online textbook.  It was all there before, but it hadn’t been very well suited to the audience, college students.  We did a couple of things to change it:

1.  Up the Interactivity

2.  Use a Balanced Tone

We shoved Captivate projects down the textbook’s throat, and it worked great.  The reason Captivate was so wonderful is it allowed us to create two-sided content that gave the students activities to do while they’re reading.  Instead of just reading, they could watch a Captivate demo or experiment with a program, themselves.

The balanced tone really means three things: it was brief (efficient and effective word use), it was professional, it was personal.  The professional-personal tone, as far as I’ve been able to gather, means disclosing professional information in a way sometimes casual.  The result is the audience feels like it’s being addressed by a person rather than a professor.

What does any of this mean for you?  Make your work interactive.  Adobe Captivate really is only one way to achieve that end–I’m certain you can achieve it with Mediawiki, Confluence, or the like.  So from now on, use your open-source authoring tools to make creative, interactive content.

Categories: General

An Old Story Retold

One issue tech writers are facing again is keeping things a little personal.  It’s an old story retold because that’s a major component of any tech writer’s professional blog.  That problem’s surfaced again in things like screen casts and podcasts.  Sometimes, authors will forget to include audio in their screen casts, or they’ll include audio that seems strictly instructional.  The answer’s actually very simple: include short pieces of audi0 (Tom Johnson recommended 5–7 seconds).  That way you include the human element, and you get a little instruction in, too.  Does that also mean being a little more efficient in word use?  Yes, but a tech writer shouldn’t have a problem doing that.

Categories: General, Uncategorized

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

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

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

So How Do You Get Ahead?

With the economy in the shape it is, we need a way to put ourselves above the competition.  There’s one way in particular that I’d like to address: dita.  Dita is a markup language (like html), it’s new, and it’s hot.  Since it’s new not as many tech writers know how to use it, but companies are beginning to think they need it.

The major advantage is once you’ve created a document in dita form, you can immediately convert it into about five different formats, including pdf.  That means you can be far more picky about format without wasting time (since the process comes out to a few seconds).  You’ll be able to make a better product in less time.  That’s good for the company and better for you.


John R Larsen

Categories: General

Jimmy Cracked a Comma and No One Cares

The title of my post is a reference back to Tom Johnson’s recent post, Duct Tape Technical Writers.  He uses that term to describe technical writers who worry more about their product and less about the grammar rules only a few really know.  He praises such writers because of three major results they produce:

1. They get the product out there.

2. They save their company money.

3. They’re aware of their audience, and they use it to their advantage (they don’t spend two hours worrying about a colon).

Is it wrong for a technical writer to care about grammar?  I don’t think it is, but maybe it’s not a bad idea for us to be careful how much time we spend on it.  If we’re costing our companies time and money that we don’t need to, we’re not doing our jobs.  So how do we strike a good balance?  I expect point three from the list above is our answer: know your audience.  If you’re writing instruction manuals, chances are your audience won’t care if a comma’s missing or if you forget to capitalize a word.  They will care if you give them a sentence that they, for the life of them, can’t figure out.  So maybe we ought to feel okay producing work closer to the copy editing level?  We can’t allow lethargy in our work, and we can’t allow perfectionism, so maybe the best idea is to allow leniency?  I think if we’re concerned about producing a quality product, but realize a few things are a little off, we can allow for some leniency in order to get our product out in the open and get our companies in the green.

Till next time,

John R Larsen

Categories: General