You may have noticed that I’ve been missing in action lately—at least on Gryphon Mountain, anyway. A couple of related factors have contributed to this.

First, I’ve devoted a lot of my attention in 2011 to fiction. I’m most of the way through my second draft of a novel. During my two-week Christmas vacation a year ago, I wrote over 27,000 words of the first draft. This last vacation, I edited and revised my way through almost the entire second half of it in my second-draft effort. I’m trying to perfect my storytelling skills. Once I complete the second draft, I’ll be reading through it in as few days as possible, just making notes as I go as to what needs fixing. Then I’ll go back and make changes accordingly.

Those who have followed the Gryphon Mountain Tales may think this strange, seeing as I haven’t posted a new tale in months. I did promise an experiment, and the experiment proved that I’m not good at serial fiction. I don’t do well when I have defined only a vague overarching storyline. I’m not saying that the Tales have died; they’ve just taken a big break.

Focusing on a novel, not to mention trying to spend time with my daughter, has left much less time for blogging here than I’ve had before.

Second, I haven’t had as much to say about tech comm this year, or at least during the last several months. As I said, I think this is related to the first cause. My mind hasn’t been on tech comm as much as before, so I haven’t had as many ideas for blog posts.

I used to have this “blog lens” through which I would view much of my professional experience. Multiple times throughout the week, I would think, “That topic would make a good blog post,” and I’d make a note. However, in much of 2011, my subconscious has been working out kinks in my novel instead.

With all of that said, however, I do have something to blog about today. :)

Part of the User Education team’s goals in 2011 was to have a team style guide finalized. I became the driver behind that effort. Mainly because of that, and probably because I’ve been doing a lot of writing and revising, the topic of concise writing has been on my mind.

A lot of the problem with common English usage these days is the padding. People insert words that don’t need to be there. Our wording isn’t precise. People feel like they have to add modifiers to their words to add importance or clarity when they don’t need to, resulting in redundancy and the weakening of the core idea.

Writers know that putting together a concise, clear message takes time. But I believe the first try would be closer to the mark—not to mention the final version—if we truly understand the language and use words precisely.

I’m sure you’d like an example. I’ll give you a couple.

“Return again.” What’s wrong with this phrase? Nothing, if it’s used correctly. Return means to come or go to a place you’ve been before. If you’re talking about returning the first time, the word already includes the idea of “being there again.” If you then leave a second time and come back, you are then in fact returning again. But most of the time, when I hear or read the phrase “return again,” the speaker or writer isn’t talking about a second time coming back, but rather the first.

“Each one.” This phrase is redundant. Merriam-Webster’s even shows one of the definitions of “each” to be “each one,” drawing on one of the other meanings of “each.” But when people say or write “each one,” they’re generally using “each” in the sense where it can stand alone meaning “each one,” making that “one” unnecessary.

I’m getting dizzy going in circles like this.

Anyway, my point with this example is that I don’t know if there’s ever a reason to say “each one” in speaking or writing. “Each” suffices.

These examples illustrate how easy and common it is in English, and perhaps other languages, to tack unneeded words on to other words.

To be precise in our writing, we should understand these nuances and then write, and edit, for them.

For technical communicators, precise language isn’t about persnickety grammarians with yardsticks ready to rap knuckles. Precise language means clear communication, less content for our audiences to sift through, and lower translation costs (where every word is an expense to the organization).

Precision is concision.

Note: If you find any unnecessary words in my post, let me know. :)

The cost keeps going upI wonder if there’s a tech writer out there—in the software industry, anyway—who would argue that being involved in the design stages of a project is a bad thing.

This theme comes up time and again among our User Education team members. Yesterday, one of us gave a presentation to our community of practice about usable design, what makes something usable, and how tech writers can contribute. She suggested we come up with some metrics that help us demonstrate how our contribution to usable design increases user productivity and lowers cost.

As part of her illustration, she showed a chart about the more and more expensive it gets to fix a bug from the requirements stage through to the maintenance stage.

An idea came to mind, and I shared it with the team, that one of the things that we can use some hard numbers with is determining how many steps it takes to complete a task. The presenter had used an example to show how a process that she would have expected to take four steps instead took twelve. If we can analyze designs and determine how many steps it takes to complete associated tasks, we can tell the project team, “That’s going to be hard to explain. That process will take ten steps (or fourteen, or twenty). And when a user sees a procedure with that many steps, the first thought is ‘This is going to be hard,’ probably followed up with ‘I hope I do it right.’ Confidence goes into a nosedive.”

› Continue reading…

Over the last few months, the User Education Team has developed a content model and a supporting style guide. Our evaluation of various documentation authoring tools a few months ago resulted in our choosing Author-it—a tool none of us was familiar with.

In our discussions about our content model, or how our information is structured, sometimes we kept drifting into talking about what Author-it would allow us to do. It was an easy line to cross. The way you approach reuse and other considerations can change based on what tool you use.

But overall, the optimal way to structure information isn’t dependent on a tool. That’s probably why our team lead kept steering us away from thinking about whether aspects of our authoring approach and information architecture would be supported in Author-it. There were parts of our discussions that blurred the lines—we would sound like we were talking about the tool, but we really weren’t.

Such discussions highlight what I’ll refer to as the core component of technical communication.

That component is the heart of the term technical communication—that is, communication.

The secondary part of that term, technical, refers to the subject matter we are communicating about. But it could also refer to the method we choose to author, organize, and deliver the content, which these days rests in technology.

Technology changes. Communication channels and content delivery mechanisms change. We have Author-it today, but something more fitting for our organization and our needs may come along in a few years. DITA has spread through much of the tech comm space, but who’s to say something more effective won’t come along in the future, or that DITA won’t evolve (see what I did there) into something better?

Yes, the technology changes, but the core principles of communication don’t.

› Continue reading…

Many times when I think of surveys, I think of the Animaniacs cartoon with the ladies who asked the three Warner siblings, “Would you like to take a survey?” There followed many questions with every imaginable permutation based around George Wendt, movies, and bean-eating.

Recently I conducted an online survey on the training and help materials for System X, a Web-based app for office staff. I didn’t ask a single question about George Wendt or beans. My two main goals were:

  1. Find out how good the training was that the respondents received in person
  2. Learn how much the respondents use the training and help materials in the application and how effective the materials are

Basic Results

I ended up with sixteen questions, some of which were demographic. According to Qualtrics (the software I used), 497 people accessed the survey, and 420 people completed it. However, I found as I analyzed the results that some respondents skipped questions and didn’t really fill it out completely. Still, about 230 out of 340 worldwide offices were represented in the result set, and I’m happy with the relatively high response rate.

As a bit of background, we have an online help system and a training page for this app. The training page has links to role-based quick reference guides in PDF and video demos in Flash. The help is your typical old-school tripane WebHelp with index, search, and so on.

Here are some key findings (numbers taken from those who responded, not the overall 497 or 420):

  • 42.7% were not aware of the quick reference guides
  • 28.3% were aware of QRGs but never use them
  • About 25% have used QRGs at least once
  • Average effectiveness rating out of 1 to 7 is 4.11 (so just above moderate)
  • About 85% print QRGs when they use them

› Continue reading…

Not that I’m the most stylish guy, but I’ve been working on a short style guide for our team. Our organization has a style guide that relies heavily on the Merriam-Webster dictionary and the Chicago Manual of Style, but it gives little attention to content regarding technology. To this point, the team has used the Microsoft style guide (third edition) as well, but it has some style specifications in it that seem pretty outdated—and rightly so, since it was published in 2003 or 2004.

The objective for our style guide is to highlight the most important considerations so they’re together in the same place. That way, when we have a new member of our team or another contributor, it’s not a huge chore to review the team style guide and get up to speed.

It was with this in the back of my mind that I went to the Society for Technical Communication’s (STC) yearly conference a couple of weeks ago. I attended some sessions that had to do with writing for localization and for accessibility. In her presentation, “DUH: Diverse. Understandable. Human,” Char James-Tanny talked about inclusion being a better word than accessibility. Her presentation came close to what I had begun thinking about.

› Continue reading…

« Previous posts | Back to top