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.

Setting up for translations

March 28th, 2014

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 American English to British English (for example, “color” to “colour”), or it could be much more complex.

It could mean preparing a document for translation into another language, or it might be taking a document written in another language and badly translated to English, and making it audience friendly.

Sometimes manuals written in foreign languages are poorly translated to English. The result can be entertaining. I recently bought a new kitchen device, a vegetable slicer. Instructions included:

  • Helps your cooking fast, joyfully with wonderfully edged strings
  • This photo shows how to make fine cut of carrot. Also, cut it in tiney [sic] pieces with kitchin [sic] knife and use for Hamburg [sic] steak.
  • Obtain strings and expose them to eunninf [sic ??] water well.
  • Made of safety type, hi-quality nylon beinforced glass.
  • Helps you in cooking fast, joyful, beautiful sharp edged!

I might be willing to cook joyful a sharp edged, but I’m not sure I’d find someone willing to eat it.

The luxuring wireless remote controlling stretches out and draws back the door translates to Deluxe Wireless Remote Controlled Retractable Gate, and we’ve all seen instructions that recommend we connect wire to Earth.

So localization performed by an English-speaking technical writer will often involving intuiting what the intent truly is, then rewriting it so that it makes sense.

I remember a document many years ago that we’d received from a Japanese client. Two of us spent an afternoon dismembering half a page of text, going back and forth with our local client, and testing procedures on the device we were documenting. When we finally deciphered what the text was supposed to say, it reduced down from about 200 words to a single sentence.

That’s one side of the coin.

The other side is setting up your material for translation into other languages. There are a few simple rules that make the job of the translator much easier:

  • Never use contractions.
  • Never use slang or idioms.
  • Never use possessives. (Instead of “the user’s first option” write “the first option of the user”.)
  • If working in a very structured layout, allow for expanded text. Romance languages (French, Spanish and Italian) take 20-25% more words than English because of the sentence structure used.

The translation service usually gives the option of applying the translations directly in the source document or providing tables of translation, where words or paragraphs in corresponding languages are in corresponding columns to the original English. I personally like to work with the tables so I can continue to maintain control over the layout and copy-fitting.

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!

 

Template talk

February 8th, 2014

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

An authoring tool is any software that supports authoring (writing) a document and formatting it before generating a PDF, HTML, or ebook output.

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 columns.
  • Paragraph controls the typeface and size, line spacing and space between paragraphs, as well as indents and justification. Paragraph formatting can also be used to set automatic numbering or bullets.
  • Character is used to apply bold, italic, underlining and any other special formatting for a single character, word or group of words within a paragraph.

More sophisticated authoring tools allow for additional style definitions, graphic images, tables, and so on. But the above are pretty much universal to all authoring tools.

The advantages of using a template are:

  • 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.
  • 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.

Direct formatting versus style tags
Writers who are not template-savvy tend to use direct formatting, that is, changing the formatting directly instead of using style tags. An example would be adding bolding and increasing the font size to “create” a heading instead of applying a Heading 1 style. This kind of formatting can create multiple issues if a document is more than a couple of pages.
For example, in Word (and most other authoring tools), you can automatically generate a table of contents (TOC), but only if the headings are standard style headings. Otherwise you would have to build the contents by hand and insert the page numbers by hand. If the pagination changes because of edits, the TOC would require manual updating—a complete waste of a tech writer’s valuable time.

You can also set up running heads and feet that change automatically with a new chapter or section, but again, only if style tags are applied correctly.

Direct formatting is an indication that the writer does not fully understand the power of his tools.

When interviewing a potential new writer, I always ask to see a sample of his or her writing in a source file—usually Microsoft Word. I ask for a sample to see how he handles language, but I ask for the source doc instead of a PDF to see how he handles formatting. If it’s a Word doc, I will turn on the hidden characters. It’s sometimes amazing to see what turns up.

Common errors include:

  • Pressing the space key to center text.
  • Pressing the space key to make a paragraph return.
  • Pressing the space key to make a hanging indent.
  • Directly formatting text to change font size, bolding, and so on, instead of using style tags for headings.

Such errors show me that the writer doesn’t have a clue about how to use a template.

Templates are a joy to build and use when understood. A failure to use a template and use it correctly literally doubles the work for the next writer on a project.

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