Channels ▼
RSS

Design

10 Things Tech Writers Want Developers to Know


I know a developer I'll call Bob (his real name is Robert). Bob does great work, producing quality software in short order, but he has a common weak point: documentation. This begs the question: Should Bob even be concerned with writing documentation? Bob is paid to write code, not technical prose.

But Bob the developer does have documentation responsibilities as the supplier of raw materials. He must deliver specifications, screen shots, diagrams, demonstrations, recorded sessions, and other relevant information to a technical writer who will sculpt it all into easily assimilated knowledge for consumption by end users. Project managers, product marketers, support staff, executives, sales representatives, and ultimately customers rely on that information. Without decent documentation, the best software and hardware may well be destined to be shelf-ware.

To help Bob provide premium raw materials to the documentation machinists on the assembly line, here are ten tried and true tips culled from seasoned technical writers.

Crisp, Clear, Concise Communication

Sometimes it takes more than cajoling, coaxing, and cursing to convince a technologist to write crisp, clear, concise communication. Sometimes it takes a federal edict. In 2010, President Barack Obama — and I'm not making this up — signed the Plain Writing Act, a law that requires federal agencies to use "communication that the public can understand and use."

The Center for Plain Language has taken the law a step further by citing violations in communication clarity from all organizations. It bestows a WonderMark after the Center's judges read a document, shake their heads, and say "We wonder what they meant."

The following two examples are parts of text that have earned the Center's WonderMark awards.

"Our goal is to keep pace with all new technical and security-related requirements. For this reason, we inform you today about the transition to a new PHP version. Please note that after the transition, the option 'Register Globals' will not be supported anymore."

and

"Welcome to the online Policies and Procedures Manual. Use the buttons on the left to view the table of the contents, or to search for documents by title or document ID number. To download any of the software packages please click the appropriate button on this page."

Avoid WonderMark-class prose, and instead strive for ClearMark awards, which "celebrate the best in clear communication and plain language."

Precise Instructions

If your life revolves around a niche software product such as Pixels with Personality, you can probably navigate the menus blindfolded. The statement "Use the Preferences dialog to change the cursor" is a clear roadmap for you.

If you're a technical writer charged with writing tomes for several software products, that statement may not get you far because launching the Preferences dialog could very well require different navigation in the various products.

Instead of leaving unmarked forks on the highways of the roadmap, nip any budding confusion by using explicit terminology such as "Use the dialog under Edit/Preferences/Cursors to change the cursor format."

Avoid OON (Overheating the Optic Nerve)
Overheating the Optic Nerve (OON) syndrome has yet to be chronicled in the Journal of the American Medical Association; but if you read manuals, user guides, and technical specifications, you have no doubt suffered its symptoms. It starts as gentle pressure in the forehead while you peruse technical literature searching for an elusive piece of information.

How does a developer cause OON? By saturating text with excessive, excruciating, exasperating details such as this example from the introduction of a product manual:

"The shipping contents of the WS-1035 include a touch-screen LCD monitor station, a 433 MHz wireless temperature sensor, the respective connecting cables, a 110 VAC adapter, and the software package on a 4.7 GB DVD disk."

You can save wear and tear on the optic nerve and cut the word count of the previous paragraph in half with this abridgment:

"The WS-1035 product includes a touch-screen, remote temperature sensor, connecting cables, power adapter, and the software package on disk."

There is a place for technical details. It's called an appendix. Put the minutia at the back of the book where it won't obscure the concepts and principles that need to be conveyed to the reader as the first order of business.

Purge Needless Politeness
Needless politeness means using words such as please, thank you, and we appreciate your devotion to our insanely great products.

Consider the statement: "If you observe the 0x5422DA error 17 times in a minute, please call our corporate technical support hotline for advice. Thank you." That statement contributes to deforestation by requiring unnecessary paper stock to express a simple instruction. No one will be offended by the politeness-free form: "If you observe the 0x5422DA error 17 times in a minute, call technical support."

Save those courtesies for making amends with technical writers whom you offended in the past with incomplete, inaccurate, or incomprehensible drafts of documentation.

Accurate, Thorough, Timely Reviews
If you think of technical documentation as a publication, the developer starts out as a research assistant collecting facts, describing processes, and assembling other raw information for authors (the technical communicators). At the end of the process, the "research assistant" dons the hat of editor and reviews and critiques the author's draft document.

A review has three main properties: accuracy, thoroughness, and timeliness. Accuracy is self-explanatory. The entire review rates a failing grade if the end result is wrong.

Thoroughness, an often overlooked goal of a technical review, distinguishes key reference documents from permanent fixtures on dusty bookshelves. It means reviewing the overall content rather than narrowly focusing on your particular area of responsibility.

For example, if you provided input for a Configuration section describing a Cursor Selection dialog, you would feel obligated to review it to ensure that it is accurate. What about the Introduction, System Requirements, and Installation sections of the document? Do they include statements such as "This product is not compatible with Windows 95," or "This product requires a minimum of 2 GB RAM"? The earnest reader, when coming upon these statements, is forced to wonder if the documentation has not been updated since a bygone era when Windows 95 and hardware with 2 GB or less of RAM was in vogue.

Other red flags are entries in the Known Issues section that list problems which were corrected umpteen releases ago.

The final key to a good review is timeliness. Don't wait until the 11th hour to deliver to the technical writer a 200-page manual with enough edits to drain several red pens. Give the writer sufficient time to incorporate your updates without creating panic during the waning minutes of the release cycle.

Reasonable Edits
Related to timely reviews are reasonable edits. In other words, trust the writer's instincts and don't pepper the draft with rewordings of sentences due to capricious preferences.

You are guilty of capricious preferences if you asked a writer to change text such as:

"Use the dialog under Edit/Preferences/Cursors to change the cursor format."

to

"Choose the dialog under Edit/Preferences/Cursors to change the cursor format."

and then to

"Navigate to the dialog under Edit/Preferences/Cursors to change the cursor format."

Establish a threshold for revisions. If a passage is factually correct and accurately conveys the information, let it stand and trust the writer's instincts. Avoid the temptation to micro-edit something just so it sounds better in your opinion.

Revere Visuals
In the evolution of computing, documentation has marched lockstep with software evolving from text to text-with-graphics to hyperlinked prose to audio and video. As a developer, you need to recognize that the raw materials you put in the documentation pipeline should also reflect a similar transformation.

A video presentation from a developer might be overkill, but you can at least share your desktop for live demonstrations of the software in action. "A combination of a text-based description and a good visual is source input gold to a technical writer," said Brian Everett, Senior Technical Information Architect at CA Technologies.

So, if you have a choice between feeding gold or ordinary ore into the documentation forge, opt for the gold.

Spell Out Acronyms

Consider the statement:

"MP performance can be impeded by noise in an ISDN BRI which can also impact LCP negotiation."

The acronyms can have a variety of meanings to the uninitiated. MP could be interpreted as Multilink Protocol or MP3 (mistyped as MP) or — if it's part of an instruction manual for an army command post — Military Police. To avoid ambiguity, take a few seconds to spell out acronyms and save yourself a round of emails and phone calls from a befuddled writer.

Be Monolingual
You might be tempted to show off your worldly nature by interspersing a document with Latin phrases and abbreviations such as those in this example:

"The wireless communication between the base station and the remote module, i.e., the client sensor, reaches distances of 100 meters in unimpeded areas, e.g., direct line of sight, ergo place the base and client in fields, beaches, urban lots, et al."

Consider the challenge of a translator who is faced with translating this verbiage to another language so the product can be marketed in other countries. Those phrases and abbreviations from the ancient Romans constitute added effort to the jobs of the translators. Not only must they translate the English words, but they must also recognize the Latin terms and translate them correctly.

Save foreign phrases for cocktail parties. In technical documentation, be monolingual and stick to plain language.

Expect Translation
If a product is successful in one country, it's apt to be successful in others. In that case, the documentation that you and a technical writing team painstakingly crafted in English now becomes raw material for translators.

As with the original draft documentation, if the assembly line is filled with good quality materials — that is, materials that were prepared with translation as an option — the translators will have a better chance of quickly producing foreign language versions.

The first factor to consider when preparing documentation for translation is communication with the translator. The translator may well be someone living on the other side of the globe who has learned English as a second language. Given cultural and time-zone differences, most communication may be by email, as opposed to direct conversations and meetings. So make an extra effort to clarify any questions or concerns from the translator in your email responses.

To help ensure that the documentation will be translation-ready once it is delivered to the translation team, here are some pointers:

Use the same term or expression for the same concept. Consider this example:

"To activate this software product, ensure that you are logged in with administrator privileges on the system. Download the kit to your computer. Run the installation utility to activate the program on your hardware."

In this case the words system, computer, and hardware could all be replaced by computer; and software product, kit, and program could all be replaced by software. Consistency in terminology will help dispel any ambiguity and potential misinterpretation.

Avoid expressions that are culture specific. Your development colleagues may understand this admonishment in a troubleshooting guide:

"The attribute not found error may be a red herring. To level the playing field, run the database table verification utility."

Good luck trying to translate that advice into Mandarin. Instead, use the more universal:

"The attribute not found error may be related to another problem. Check the database by running the table verification utility."

Use plain words. To ease the translation process and avoid violating the Plain Writing Act, use simple words instead of pompous synonyms. Here are a few examples:

Instead of:  Use:

ascertain

find out

expedite

hasten, speed up

necessitate

need, have to, require

prior to

before

subsequent to

after

Use vertical lists. Read the following passage a few times while noting the temperature of your optic nerve:

In the Home screen, select one of the categories or select the Customize Selection to customize updates that you want to apply to the system depending on the requirement.

Now read:

In the Home screen, do one of the following depending on the requirement:

  • Select one of the categories.
  • Select the Customize Selection to customize updates.

Vertical lists, as shown in the second italicized passage, are key to breaking down technical information into easily assimilated chunks. Use them liberally.

Use active voice wherever possible. Compare the active and passive forms of the following instruction.

Passive: Any change to the configuration must be updated in the master file.

Active: When you change the configuration, update the master file.

The passive voice conceals who or what does the action, and it requires more words than the active voice. In short, passive is more difficult to translate than active, so choose active wherever possible.

If you get into the habit of following these recommendations, your customers and your colleagues will be thankful. Your customers will especially reward you by using your products — and using them correctly.


Edward J. Joyce, a software engineering manager, strives to provide "source input gold" to his writer colleagues at CA Technologies.


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 

Video