Archive for 'Writing Theory & Practice'

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. :)

Tags: , , , ,

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…

Tags: , , , , , , ,

Sometimes I get ideas about a problem I’m trying to solve once I’ve stopped actively thinking about it and have let it drift into the back of my mind. With Project Pinnacle, something escaped my attention until a few weeks after my visit to the pilot site.

Well, it didn’t entirely escape my notice, but its implications for documentation and training didn’t hit me immediately.

The thing I noticed while watching users try out my quick reference guides was that they tended to follow only the first few steps of the procedure. They would look at it long enough to get to the screen where they performed the task, and then they would try to do the rest without the guides.

One of the reasons for this is that they had to keep glancing between the monitor and the paper, which made it easy to lose their place. Trying to use a finger didn’t help much either because at some point they had to start typing.

A few weeks after my visit, I got an idea of maybe a true quick reference guide that would fit what they needed. Since they relied on the printed procedures only for navigation, why not just provide the navigation steps?

I put together a version of each guide that listed the steps with double angle brackets between each step. This condensed the existing material from about four pages for each guide down to under one page. I haven’t tried these versions out yet. The project manager wasn’t in favor of the version of the guides that have the screenshots with callouts because of the cost of keeping the screenshots current for all languages.

When I first reported to the project leadership about my visit to the pilot site, I pointed out that a way to improve our training of our audience and at the same time reduce documentation costs would be to provide more prompts in the application. I’m not trying to reduce my workload, but I believe that the more help you provide in the interface, the less help you have to maintain elsewhere. I know, not real profound, but it’s not something very many product designers think about.

Since then, I’ve provided prompts and descriptions for a number of application screens and features. We’ve seen a direct impact of this as we’ve worked on the training video scripts. We want to keep the verbal explanations simple and let the features be demonstrated so that we don’t have to rerecord the audio if features change. The fact that we’re including help in the interface helps us do this because we can leave much of the explanation to the application itself.


Image credit: Salvatore Vuono, freedigitalphotos.net

Tags: , , ,

Last week I visited the pilot location for Project Pinnacle. My focus was to see how well my first-draft quick reference guides worked, but I spent some time training.

The office staff tended to want to ask me how to do things and be walked through it, but I took those times to ask them to test out the instructions for me. However, on one occasion, I had to guide a brand-new user through a somewhat complicated scheduling procedure while she was on the phone with the person setting up the appointment. I figured it would be better to help her through that one because she’d feel enough pressure from trying to do it right and in a timely manner.

In addition to notes on improvements to make to the guides, I kept other notes. The rundown:

  • 5 tasks to add to the guides
  • 14 other changes needed to the guides
  • 20 feature or change requests
  • 10 bugs
  • 14 miscellaneous items that were questions, observations, or usability problems

› Continue reading…

Tags: , , , , ,

I’ve been reading Ginny Redish’s book, Letting Go of the Words: Writing Web Content That Works. It was a bit slow at first because the early material is pretty basic. And I came into it with the preconception that it wouldn’t apply much to documentation, since we write help systems and manuals.

In light of our team’s search for the tool that best meets a set of specific requirements, I’ve decided that Redish’s book has everything to do with what I do—or what I should be doing.

My Beef with Tri-pane Help

If you’ve been reading this blog for a while, it’s no secret to you that I’m not a big fan of tri-pane help. I think it’s dated and is associated in people’s minds with unhelpfulness.

But in our search for a tool that will give us a more robust Web output, I’ve discovered the main reason I don’t like tri-pane help.

› Continue reading…

Tags: , , , , , , ,

In my initial conversation with the manager of Project Pinnacle, we decided on a set of role-based quick reference guides as the documentation for the application.

I ended up with about five weeks to complete these guides in the midst of other projects. After a demo of the application given by the lead tester, I sent the manager an outline of each guide. He didn’t get back to me right away, so I started writing the guides while using a test version of the application.

The guides’ structure was pretty simple. On the first page, I included a screenshot with callouts that explain the navigation structure of the application: header, subheader, tabs, links, buttons, and so on. The hope is that this would reduce the amount of instructions needed by covering the basics together. After basic navigation, I covered the main tasks for the role in question.

› Continue reading…

When deadlines are hurtling toward you with all the leniency of a runaway dump truck and you realize that you have to sacrifice something in your user education project, what do you choose to drop?

Sometimes you can even see the problem coming when you start the project. Not everything will make it, so you have to let some things fall by the wayside. Maybe it’s one of the rounds of reviews. Maybe it’s the troubleshooting section or the index. Maybe it’s the screenshots or fully colored and designed diagrams.

I confess that when I need to get the job done and I’m pushing myself to write, I feel the temptation to make the worst shortcut of all.

I’m tempted to make assumptions and trust them instead of getting off my rear or picking up the phone and asking someone, such a subject-matter expert or a user.

This is the shortcut that tech communicators can least afford to take.

Why?

› Continue reading…

Tags: , ,

The world connected

With the increasing emphasis in business on compelling content, I’ve been thinking that the field of translation may shift its focus as well.

The goal of most translation services appears to be speed, affordability, and accuracy. For example, Verbatim Solutions’ website says: “In all cases, Verbatim provides the right solution to help clients minimize costs, accelerate time to market, and ensure quality.”

But what is quality? Is it 100% fidelity to the original text?

Or is it conveying a message in a way that preserves the original intent—or even adjusts the message based on the cultures of those who speak the target language?

› Continue reading…

Tags: , , , ,

When getting a recent set of release notes ready, I sent them to the product manager for feedback. He emailed back and pointed out the concepts we needed to emphasize with a change we were making. I struggled to work them back in to my copy without making it more than people would read.

I decided I needed to take a step back and start over. I took some quick steps that helped me produce a much clearer and stronger message about the change being made:

  1. Open a blank document.
  2. Write in as brief sentences as possible the concepts that you need to get across. Boil the message down to its essential parts.
  3. Revise minimally.

› Continue reading…

Tags: , ,

In the project portfolio where I work, we have several applications in maintenance mode. A number of developers and testers, some previously assigned to dev projects and others relatively new, may work on bugs from any application at any time, and most aren’t familiar with the applications yet.

My cubicle is next to that of Matt, one of the testers. One day he was trying to follow instructions in some test cases and hit a wall because of lack of detail. He called over Nathan, another tester in a neighboring cube. They launched into a discussion of how much detail should be included in test cases.

Matt’s problem was steps that assumed prior knowledge. It would be a general step like “Create a payment to a landlord.” Well, how do I do that? he wondered. A number of steps are involved in creating a payment, and he didn’t know what they were. The test case was obviously written for someone with a certain level of knowledge about the application. Matt needed more detailed steps.

› Continue reading…

Tags: , ,
« Previous posts Back to top