Precision Bloggage from Precision Wordage

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.

Your manual seem not understand?

February 7th, 2008

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

“Two sets of eyes, minimum”

October 20th, 2007

If I had a quarter for every time I’ve been asked, “Why do you charge as much for proofreading as you do for writing?” I couldn’t retire. But I could fill a swear jar.

At Precision Wordage, we follow the rule “two sets of eyes, minimum.” No matter how good the writer, no matter how clean a draft, whether you write it or we do, an author cannot proof his own work.

What skill set does it take to do a good proof job?

The most vital skill is the ability to spell. Spell checkers can catch flagrant misspellings, but won’t catch those nasty homonymic errors. “He road the hoarse across the open rode, ignoring his horse cough.” You see what I mean.

The next skill is grammar. When I was a kid, I used to diagram sentences for fun. It came as a shock to discover that diagramming hasn’t been taught for decades. Makes me feel old. The PWI team knows their syntax (the rules for forming words into correct sentences) cold.

Then there’s style. The basic bible for publishing is The Chicago Manual of Style. But then there’s the Microsoft Manual of Style for Technical Writing, and who knows how many other upstart new publications to cover the morass of media rules, regs, recks and refusals on grammar relating to technology, not to mention classics like Strunk and White’s Elements of Style. Our guys know `em all. And then some.

A proofer has to be able to think. For example, we deal with a lot of new technology, with scores of words that didn’t exist twenty years ago. If the proofer hits a term that’s spelled inconsistently in a client’s document, he’ll go online and search until he finds the most common usage, and recommend that the client use it that way. And he’ll stick it in the style notes for the job. If the client wants to spell a word differently, that’ll go in the style notes as well. And the proofer will know that with client A he always uses “dingles,” but client B expects “Dingles” to always be capitalized.

In proofreading, like most things in life, there are no absolutes. But we come close when it comes to catching those pesky little errors that detract from a document’s polish.

- Su