The bottom line on any technical document is whether the user can read, understand and successfully apply the instructions.

So how important is readability?

Think of it this way. You have a Ferrari parked in your driveway—a vibrant red package of elegant engineering, speed and sex. This is the car you’ve wanted all your life. You can already feel the pressure of the acceleration pushing you into the driver’s seat, you can hear the wind beating against the windshield… but the dealer just told you the factory didn’t include a key with the car. Did you just spend a quarter mil for something you can’t use?

Readability is the key that turns on the value in your technical manuals, guides or any other user instruction.

Testing for readability

The Flesch-Kincaid readability tests were originally developed for the U.S. military for use in assessing the accessibility of technical manuals. Could the guys in the classroom assimilate the data fast enough to get the technology viable? Could the grunt in the field follow the instructions without the aid of an instructor? These tests are based on mathematical analyses of a document’s content.

In the Flesch Reading Ease test, a higher score indicates easier readability.

For the Flesch-Kincaid Grade Level test, the analysis gives a grade level. The higher the grade, the harder the read.

Just for fun, we took a legacy manual from one of our clients and ran it through these tests. We then did a first draft rewrite and ran it through again. The results were interesting:

And this was only first pass!

Active or passive?

One of the things FK tests for is use of passive language. For example, “The button is pressed…” (passive) versus “Press the button…” (active). Active voice spurs the reader to do something, while passive voice tends to make the data sound less important.

If you expect the user to do something, use the active voice.

Other elements of readability

These FK tests address only one aspect of readability—language. The are other factors that contribute to a technical manual’s usefulness, including font style and size, column width, and use of white space.

Another factor that can dramatically improve the user’s understanding is technical illustration.

At Precision Wordage, we take all of this, and more, into account when developing any kind of user instruction, because the bottom line on any technical document is whether the user can read, understand and successfully apply the instructions.

- Su

Anybody can write a manual, right?

I don’t think so.

I’ve known a lot of tech writers over the decades I’ve been in this business–some of them really, really good, some of them just dreadful, and everything in between.

I have also identified the qualities that make for a really good tech writer, and if even one of these is missing, the quality of his or her work will suffer.

The first of these is a passion for communicating. This is most often manifested in the arts. A tech writer who is also a poet, artist, musician, or so on, will have a quality about him or her that adds that little extra element of care to the work of technical writing, a determination to communicate in a way the audience can understand and appreciate.

Next is the desire for perfection. Why use five words when you can say the same thing with two? Start with clean, clear, crisp prose, then edit it down until you have the essence of the communication.

Finally, there is sense of humor. At Precision Wordage, new clients often bring us in on a project about 2 months too late and our deadlines are usually intense. The ability to laugh makes this kind of pressure fun and challenging instead of painful.

-Su

Last year, engadget.com published an article with a headline that included “promises ’service manuals that don’t suck’.”

It surprised me that this would be newsworthy–the “promise” from the manufacturer included features we’ve been implementing at Precision Wordage for well over a decade–then I thought about some of the resistance I run into with clients when I’m trying to get them to step away from failed methodologies in their technical manuals.

A recent example was a client who brought us in because, in his own words, he wanted the company’s tech pubs “to move into the 21st Century.”

The first thing we did was to revamp the document appearance, adding white space to the pages, cleaning up the headers and footers and “branding” them in keeping with the company’s marketing standards. Next, we adjusted the language to accommodate the target audience. We cleaned up the graphics so they were actually useful, replacing poor-quality photos with crisp line drawings. And finally, we reorganized the sequence of the contents so the user didn’t have to wade through 50 pages of background before getting to actual procedures.

Well.

From day one, we were fighting with the one in-house tech writer who’d developed all of the old, unmanageable standards. His boss backed us up, so we continued to improve on the documents. Then there was a personnel shift, and the new power over tech pubs did not share the previous vision. The docs were moved back into the old template, the in-house writer returned to his complicated language constructions, and our contract was not renewed.

It’s not the loss of the client that bugged me–that happens. It’s the loss of every bit of innovation we brought in because of the client’s failure to follow the vision of his predecessor.

But there’s another side to this coin.

I got an email recently from a client who actually demanded that we push the envelope on friendly and usable technical documents. He said, “The facts are that the tested time to install for the [new product] was approximately one half of the time for installing the preceding [old product], call volume decreased by almost one third and product registrations increased in the low double digits. I also tracked various press coverage and noted a positive effect on product reviews. More importantly, customer satisfaction scores started climbing which was important for customer loyalty and brand reasons.”

Now that was a fun project.

At Precision Wordage, we are passionate about the work we do, and our sole objective is to make our work as useful, informative and as pain-free as possible. We throw combined decades of experience at accomplishing this, and take pride when our work wins awards.

If you share our desire to continually improve your users’ experience with your documents, contact us and let’s see if there’s a way we can work together to bring your vision to fruition.

-Su

A template is a set of predefined format instructions that can be applied to a document quickly.

Just about any authoring tool, including Microsoft Word, has the capacity for using a template.

Templates address three basic levels of formatting:

Page addresses parameters for page size, margins, headers and footers, and so on.

Paragraph controls the typeface and size, line spacing and space between paragraphs, along with indents and justification. Paragraph formatting can also be used to set automatic numbering or bullets.

Character is used to apply bolding, italics, underlining and any other special formatting for a single character, word or group of words within a paragraph.

The advantages of using a template are many:

Speed: Formatting with a template tag usually requires a single click.

Consistency: All documents formatted with the same template have the same look and feel.

Clarity: A well-designed template will enhance the communication for the reader, whether it is for a technical manual, quick start guide or any other type of documentation intended for the user.

Ease of update: With a well-made template, it doesn’t matter whether the same writer does the updates or someone else, because there won’t be an issue of trying to match the formatting or figuring out how (or even why) the writer used the formatting he or she did.

- Su

Technology is a wonderful thing… when it works.

But sometimes technology fails us. Hardware breaks, software crashes, power goes out, a cable comes loose… the caprices of technology and vagaries of life are infinite, virtually or otherwise.

However, there is one vital action that safeguards our work against all but extreme acts of nature.

Save frequently.

When writing or editing on the computer, save your work frequently. Most PC programs use CTRL S to save. Train your fingers to use this or whatever save command is available in your application. Train your fingers to automatically press the save command key sequence after every major edit, or every time you go to a new column or page or reach for your coffee. DO NOT DEPEND ON THE AUTO-SAVE FEATURE to do your saving for you. Restoring a document off an auto-save version can be messy and incomplete.

There is nothing quite as frustrating as to be on a roll with writing or editing, where all the right words are suddenly falling into place, the language is flowing and all is right with the universe, then—bamm!—something breaks, and that 30 minutes of sheer genius you just experienced has gone to bit heaven. And that’s the kind of moment when these things usually happen.

So save frequently. Save every time you move from one application to another. Save every time you get up from your chair. Save when you sneeze. Save when the phone rings. But save AT LEAST every 15 minutes and you are unlikely to ever lose a large part of your work.

-Su

Over the decades, I’ve worked with every kind of client imaginable, from Fortune 500 corporations to small start-ups working on half a shoestring. They all have one thing in common: the desire to predict costs on any technical writing project.

Estimating what a tech writing job will cost involves a number of factors that range from the audience you are writing for to the responsiveness of the review team and the number of reviewers on a technical document. The simplest way for a tech writer to approach a documentation project when estimating costs is to start with the end product and work backward.

Something to keep in mind always when working out the content on a project is the 20/80 rule: Eighty percent of the users will use twenty percent of the features. This is important to keep in mind because this drives the amount of content to be included, which is a very important element in costs.

Another key element is the availability of subject matter experts, or SMEs. How available are the SMEs? Are they the preliminary interview subjects only, or are they also part of the review team?

Reviews are also important to consider when estimating the cost of a job. A short review lineup will always keep costs down compared to a document-by-committee review. The more reviewers stirring the doc pot, the more likely you will have conflicting opinions, which translate exponentially to extended time and frequent rewrites and rewrites of the rewrites.

When I estimate a job, part of what I do is alchemy. I’ve been doing this kind of work for so long that my “guesstimates” tend to be fairly accurate. The only area that is hard to predict for me is the review line when working with a new client.

-Su

My first tech writing job was in 1984. I was part of a documentation team for a mainframe system in a large corporation.

A couple of weeks after I started, the supervisor called me in for a review meeting to find out how things were going.

I started to describe the direction I felt the documentation needed to go.

He interrupted me. “Where are the pages you’ve done?”

Pages? “You mean my notes?” I said.

“No. I want pages. Paper by the pound. You know, poundage.”

Poundage?

“I want poundage,” he repeated. “I don’t care if the procedures are right or wrong. Nobody’s ever going to read the manuals anyway. But we’re spending a lot of money on your writing team, and I need to justify that expense. I can only do that with poundage.”

My team and I started turning out pages. When the supervisor would come by to see our work, he wouldn’t read it, he’d just pick up the dot-matrix printout and heft the weight, perforations and all. The heavier the pile, the happier he was.

I didn’t like it though. I’d been writing articles and fiction for a decade, and I was accustomed to audiences. I wanted to satisfy the audience even if it wasn’t entertainment. So despite the poundage demand, I made a point of testing every procedure on the users who’d eventually use our tech writing to ensure it would be read. Because of the demand for poundage, I learned to write fast; because of my own fastidiousness, I learned to write well.

Today, poundage is no longer demanded—in fact, the field has swung to the opposite extreme. The more concise the writing, the better the product in technical documentation. But more words or less, it always starts with a writer’s understanding of who he or she is writing for, and what that audience will need to know from the document to make it useful.

-Su

Technical writing has evolved over the decades I’ve been in the field. Twenty-five years ago, most instructions were text-based. Graphics programs were rarely used, and the ones that were available were so slow that it was easier to re-create DOS-based screen shots in Word using a non-proportional font than to try to capture a screen image for insertion into a technical document. I remember the hoops I would jump through just to import a new font into Word.

Over the last 30 years, the audience has changed as well. A few decades ago it was safe to assume that anyone working on a computer had a high level of literacy and ability to follow written instruction. Now there’s a strong chance that your audience doesn’t have English as its first language, and if the software design isn’t intuitive, you’re gonna lose your reader on the first nomenclature stumble.

Technical writing isn’t just about documenting software anymore. One of our favorite things to document at Precision Wordage is consumer electronics—anything from printers to big screen TVs. Over the years we have moved more into visual instruction, and stay away from excess verbiage whenever possible.

tell
For example, let’s take a mouse. This mouse happens to be wireless, which means it will need a battery. You could give the battery installation instructions as straight text:

1. Slide the battery cover away from the center of the mouse until it releases, then flip it open.
2. Insert the battery negative end first.
3. Close the cover.

Workable, but uninspired.

show
Or you could show it:

show and tell
Best of all possible worlds provides a balance of text and graphics:

In any kind of technical writing, the more you can show, the easier it is on your reader.

The recession isn’t coming; it’s arrived. Companies are getting more and more budget sensitive, and looking for ways to cut costs. This is impinging on the field of technical documentation. I know of at least one major electronics company that asked its technical writers to take a pay cut. The writer I know there took it gladly, happy to have not been laid off completely like some of his co-workers.

But technical publications still need to be produced. As long as products are going to market, the technical documentation has to be there on how to use them.

Some companies are turning to off-shoring, but, in the words of one former client who was forced by upper echelons to go that route, “It’s a challenge since English is not the first language of the writers… things … need to be sacrificed along the way.”

Is there another solution? You betcha.

On-shore outsourcing.

At Precision Wordage, we’ve been taking only outsource projects now for about 15 years. The projects we work on minimize client costs because the client pays only for the actual writing project (and gets a high quality product in the process). No overhead, no paid vacations, no severance packages when the project is over.

If your company is looking for ways to cut costs, consider using an outsource company. Crunch the numbers and you’ll discover that technical writing from an outsource vendor will deliver the most bang for the buck, especially if you can negotiate a flat bid or not-to-exceed deal.

And if the writer is American, chances are the technical communication will actually communicate.

- Su

Have you ever opened a manual and wondered what planet the writers lived on? It probably wasn’t localized.

Localization means adaptation of the language in a document or software to a new culture or region. This could be as simple as changing the spelling from British English to American English (for example, “colour” to “color”) or it could be much more complex.

Sometimes, when manuals are written in foreign languages (particularly East Asian languages) and translated to English, things are somewhat less than intelligible. And hijinks ensue. We writers affectionately refer to such abominations as “Engrish” or perhaps “Chinglish” in the case of a certain well-known language.

The problem arises when the translation is done by machine “translators” (which are mostly little more than word substituters) or persons who are barely literate in English. Underneath that, the quality of the original manual in the foreign language may not have been particularly good. The result is often a very confusing (and sometimes highly amusing) set of instructions.

“The luxuring wireless remote controlling stretches out and draws back the door” (translation: “Deluxe Wireless Remote Controlled Retractable Gate”) may be hilarious, but it doesn’t exactly put across the right concept.

But what does one do about it?

That’s where competent tech writers come in. We can take the most garbled manual and turn it into a sparkling jewel of clarity and usefulness. A good tech writer has a “knack” for deciphering what the original-language writer was trying to say, however goofy the translation, and re-expressing it in English that can be understood.

- David