Precision Bloggage from Precision Wordage

Get it in writing, keep it in writing

July 22nd, 2014

When you have a face-to-face meeting with a client or project group, take notes. After the meeting, summarize your notes as brief bullet points and email them to everyone who attended or would have a vested interest in what was covered. This ensures that you all agree on what was covered.

When you have a phone meeting, do the same.

These simple points of documenting all communications in writing have proven to save enormous time and money, and to prevent massive misunderstandings and the resultant upsets and loss of business that inevitably come from not maintaining this policy to the letter.

Remember: The spoken word is in the air; the written word is always there!

A bug is an undocumented feature

May 21st, 2014

There’s an old joke in the software industry: A bug is an undocumented feature.

Some software is so beautifully designed with screens that are so intuitive that a manual just isn’t needed. I admire this kind of user-friendly interface, but it’s not what keeps me in business.

Sometimes you have to document software that is badly designed or buggy. When this happens, the tech writer is definitely earning his keep.

Maybe you have a screen that goes black if the user tries to move backward through fields by pressing Shift+Tab. This datum had better be in the manual!

What makes an expert an expert

May 8th, 2014

I have a friend who defines an expert as “someone who’s made all possible mistakes.”

While this is an entertaining definition, I have expanded it:

An expert is someone who has made mistakes and is proficient in identifying them as mistakes, who can work out how to quickly and effectively correct them, and who then establishes best practices to keep such mistakes from reoccurring.

Words and phrases that just don’t work

April 16th, 2014
, and then The Microsoft Manual of Style for Technical Publications states that this is acceptable because then is not a coordinate conjunction. However, a comma can serve as a conjunction, so I prefer to omit either the comma or the word and.Press the Enter key, then type the next line.

Press the Enter key and then type the next line.

in order to, in order that These phrases seldom add useful meaning and tend to clutter sentence structure.
simply If it’s so simple, then why do you need to document it?
please It’s an additive word that contributes nothing to a sentence.
from vs. than The adjective different is usually followed by from. Use from when the next element of the sentence is a noun or pronoun.Correct: The result of the first calculation is different from the result of the second.

Incorrect: The result of the first calculation is different than the result of the second.

may vs. can Try to avoid using may, which shows permission or possibility. Can indicates ability, and is better in most contexts. Examples:The software can run in the background.

The software may crash when in beta test.

which vs. that Which refers back to an entire preceding statement rather than to a single word: She ignored him, which proved unwise. “Which proved unwise” refers to the preceding phrase, “She ignored him.”That should be used to introduce a defining clause, which identifies what is being discussed. When used this way, it should not be preceded by a comma. The book that Jack read was burned. “That Jack read’ describes the book referred to.

That may be omitted when the subject of the clause is different from the preceding clause. “The coffee that I had last night kept me up” could be shortened to “The coffee I had last night kept me up.” Exception: If you’re setting a document up for translation, do not omit the word “that” as it could create some ambiguity for the translator.

Engineer vs. end user and the eighty/twenty rule

March 26th, 2014

Engineers are often the worst writers—particularly those engineers who have worked on the product you’ve been hired to document.

There’s a great rule that applies beautifully to documentation: eighty percent of the users will use twenty percent of the features.

Engineers are interested, as they should be, in all the “nuts and bolts” that make a product work. This applies to hardware and software. The problem is that engineers, when writing, want to share all the nuts and bolts with the reader.

The end user, on the other hand, just wants a simple nail: which button pushed or switch flipped will produce the desired result? He could care less about what is happening in the background. When designing documentation, this should always be kept in mind. What are the features the user will be most interested in? Do those features come up quickly in the manual?

As a tech writer, you are the bridge between the engineer and the user. To write intelligently and usefully, you will need to understand the subject matter you’re documenting far better than the user will, but that doesn’t mean you have to dump all of your hard-won knowledge into the manual.

Eighty percent of the users will appreciate it if you don’t.

If the user can’t use a datum, throw it out!

 

On readability

March 14th, 2012

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:

Flesch-Kincaid test results

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

What I look for in a tech writer

March 8th, 2012

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

Pain-free technical manuals

February 14th, 2012

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

Advice to all writers everywhere

January 17th, 2012

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

How to bid a job

January 11th, 2012

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