Archive for December, 2009

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

Problems with Collaborative Authoring Projects

It should be pretty cut-and-dry to us what the benefits of collaborative authoring are (namely two things: 1) input from several different authors and 2) rapid production rates for content).  Every business that can afford them wants those benefits, but that’s just the point–costs shoot up when you move from single-source authoring to collaborative authoring.  On average costs jump from four figures to five.  That cost jump scares a lot of people, and even the well-to-do businesses are still stingy.  So far programmers and tech writers have tried handling the problem by producing free software (e.g. Mediawiki and Drupal).  You can find a quick list of programs and figures on Anne Gentle’s blog.

If you want to do some collaborative authoring, Mediawiki is probably your best bet.  It’s a name I’ve heard tossed around for a while now, and it seems to have Tom Johnson’s approval (maybe I should have asked first?  I know he’s using it right now  because he was assigned to do so for a given project, or conditions to that effect).  The big benefit is it’s free for you, but that doesn’t mean it’s cheap; it’s capable of doing it’s share of work.

HATs are the Energizer Bunny

I’m getting a little sarcastic about the conversation on HATs.  I started this blog as a way to keep track of the new developments in technical writing, and the hot thing now is open-source authoring tools like Mediawiki and Confluence 3.1 Beta.  Still, I can’t say there isn’t a good reason for it.  Let me just address one thing you’ll be able to walk away with and use.

If you create something on Mediawiki, you can adjust the skin.  Before I show you how, allow me to make the disclaimer that my attempts to download Mediawiki have been unsuccessful–my computer won’t agree with it.  We have from Wikipedia:

A default skin can be set for new users of a wiki by setting the variable $wgDefaultSkin in LocalSettings.php to the lowercase skin name specified in the skin file. Users can still change their skin later by going to their preferences page. To change all existing users’ skin settings, use the userOptions.php maintenance script.  The syntax to use on the command line would be:

$ php userOptions.php skin --old <old skin name> --new <new skin name>
Categories: HATs

The Continuing Conversation with HATs

I’ve looked a little bit and saw the conversation (or one of the conversations) in technical writing is still on help authoring tools (HATs).  Tom Johnson’s convinced traditional HATs will fade, and I’m convinced it’s foolish for me to question such a reputable tech writer.  The idea, as far as I can gather, is to give the author as much control over the HAT as possible.  That means the emerging HATs will be a little less accommodating to beginners, but it also means greater versatility, which is what we need.

If you take a look at Mediawiki, you’ll see a lot of what I’m talking about.  You need to know a little about programming in order to make much happen.  You’ll be doing a lot more work in CSS, one of the main reasons being that’s how you arrange and manage your display.  One other major source of programming is content management.  There’s no user interface, and that takes some extra work, but devoting some real time to localsettings.php will take care of that.  Localsettings.php is the file you’ll be working with to manage your content.  The beautiful thing is once you figure out CSS and localsettings.php, you can do just about anything you care to do–things you couldn’t have done with a traditional HAT.

Categories: HATs

A Fine Way to Reach Your Audience

It’s called screen casting, and it’s not necessarily too difficult.  If you have a microphone and webcam that work, you’re all set (for an ideal setup, visit Tom Johnson’s blog,

Screen casting can be something as simple as a link to a youtube video.  The point of using it is the same reason you use Captivate: to keep your audience around.  When they’re watching footage of you speaking, they don’t have to read a word, and they like that.  The other great thing about screen casting is you can place the link anywhere.  You could have one in the middle of your blog, an online document, or a website.  It seems to me like there are two wins: first, screen casting catches your audience, and second, it’s a fairly versatile tool.

Categories: Screen Casting

Making Content Effective, Part Two

Another great way to make content effective is giving the reader something to do.  Using pictures is good–and sometimes that’s all you need–but that doesn’t give them the ability to interact.  Adobe Captivate does.

You can use Captivate to take footage of anything you do in another program.  Once you’re done taking that footage, you can add tons of things to it in order to draw your audience in.  Make sure you don’t go overboard; that will ruin it.  Just adding some audio, however, can make a huge difference.  If you have a PowerPoint presentation you want to improve, you can record it into Captivate and add rollover text, buttons (which take you to another part of the presentation), audio, or anything else.

How does that make for interaction?  If you add audio, you just gave them something to listen to and guide them through your project.  If you added rollover text, you gave them a reason to move their mouses.  If you added a button, you did the same thing (when they click, something happens).  If you want to give your audience little reasons to stick around, Captivate’s your new best friend.

Categories: Interactivity