Eight Essential Writing Skills For Techies*

(E-WRITE)
We begin this issue with a bold statement: technical people need adequate writing skills.  Though we realize many techies despise writing—“I hated English; that’s why I became an engineer in the first place”—techies in today’s workplace need to be able to write.  Besides, the whole concept of being either non-literary (a techie) or non-technical (a wordie?) is dead.  Fifteen years ago, we all had one stubborn non-techie colleague who “wasn’t into” computers or “didn’t do” e-mail.  But today, being unwilling or unable to use current technology simply isn’t an option, nor is being unable to write clearly.
 
Why (Some) Techies Can’t Write

• Writing was not part of their professional education.  Techies may have struggled through Comp 101 during freshman year in college, but many did not have an upper-level writing course to help them build on-the-job writing skills.  Thankfully, this situation has changed.  Most colleges require Comp 101 plus an upper-level, discipline-specific writing course.
• Techies frequently communicate visually.  Instead of words, they use flowcharts, blueprints, satellite images, and schematics.
  
• Techies tend to be “trees” people.  They’re immersed in details and may have trouble seeing the “forest.”  Good writing requires describing the forest, then pointing out individual trees.
• Not being able to write (or not wanting to) is part of techie culture.
  

• If they can’t write, they can’t share what they know.  Expert Dorothy Winsor, famous for studying the communication failures that led to the Challenger disaster, puts it this way:  “Effective communication generally, and effective technical writing specifically, is essential to success in engineering because it conventionalizes knowledge and makes it shareable."
• Poor writing skills are costly.  In 2004, the National Commission on Writing estimated that remedying deficiencies in writing costs American corporations as much as $3.1 billion annually.
• Good writing buys techies a seat at the corporate decision-making table.  When techies represent their ideas well in writing, management can understand what techies need, want, or have accomplished. 
• When techies can write, the rest of the world can do. Ever consulted a User Manual and found that it actually helped you?  If so, thank a techie who could write.

• The ability to write marketing copy for a variety of channels: print, web, e-mail
• The ability to write journalistic products: articles or press releases
• Foolproof editing or proofreading skills
  

1. Put the bottom line up front (B.L.U.F.).
   Most forms of workplace writing provide a privileged place to put the B.L.U.F.  Reports have executive summaries, e-mails have subject lines, and scholarly articles have abstracts.  Figuring out what the Bottom Line is and stating it clearly Up Front is an essential writing skill for techies because their documents often contain a wealth of detail.  Without a clear B.L.U.F., data-rich documents read like data dumps.
   
   
2. Write message headings.
   Headings make writing scannable and enable readers to read the amount they want, in the order they want.  Techies should know how to write message headings, ones with verbs in them, because they help readers the most.  So in a software user guide, the heading Reports is okay, but the heading Create and Print Reports is truly useful to a scanning reader.
   
   
3. Write easy-to-follow instructions.
   For many techies, the bulk of their writing involves explaining how to complete a task.  Techies will make their own lives easier if they know how to write instructions that include all steps in the order they need to be performed.  Techies should write instructions that:
   
   • Begin with a B.L.U.F. statement summarizing the task.
   • Start each step with a verb.
   • Put notes or warnings at the start of the instructions, or just before the step to which they refer.
   • Use numbering and bulleting correctly.  Use numbers when order is important; use bullets when order is not important. 
     
     
   Example: Numbers for sequenced content
   To get help:
   1.    Click the Help icon at the bottom of the page.
   2.    On the Help page, click on the name of the product.
   3.    On the Product Info page, type the product’s serial number in the box.
   
   
   
   Example: Bullets for non-sequenced content
   To get help:
   

   • Click Online Help to access an HTML help document.
   • Call the Help Desk at 888-555-1234.
   • E-mail the development team at devteam@abccompany.com.
   
   
4. Know how to use terms.
   Techies are famous for using lots of specialized language.  But they must use it well or technical terms can add to a reader’s burden.  First, they must use terms consistently.  Using clinical study, clinical trial, clinical protocol, and clinical research interchangeably will leave readers in the dust.  Techies must know when readers need terms explained and have a set of strategies for explaining them.
   
   When to explain terms:
   
   • The document is written for non-techies, or will be used by techies and non-techies alike.
   • There’s controversy about what the term means or the term’s new.
     
     
   How to explain:
   
   • Provide a synonym for the term.
   • Offer a definition of the term in parentheses.
   • Give a written or visual example or illustration.
   • Link to a complete glossary.
   • Spell out the acronym.
   
   
5. Use an appropriate tone.
   The techie stereotype suggests a lack of social skills, but we haven’t observed this in the techies we know and love.  We have observed that techies adore brevity, and they frequently strive to keep their writing short at the expense of sounding human.  Techies should know that their tone in writing should match their purpose for writing.
   
   For example, a salesperson for a manufacturer e-mailed a techie colleague to ask when the latest product, “Lot 25005047,” would be ready.  Here’s the techie’s response: “i assume you checked if we are out of lot 046 already????? anyhow, 047 looks ready on march 5.”  While this e-mail does answer the question about when Lot 25005047 will be ready, the writing sounds testy.  This tone doesn’t match the techie’s purpose for writing: to provide a colleague with the information he needs to do his job.
   
   
6. Write concisely.
   Concise writing is succinct—no fat on the bones. Concise technical writing often involves using lists, tables, and graphs which show relationships better than words can. Here’s an example showing how a list or table presents information more concisely than a paragraph.
   
   Example: Wordy Text
   The investigator database includes three types of investigators. Each type of investigator is responsible for a different function. Basic Investigators, as the name implies, are responsible for basic pre-clinical research.  Clinical Investigators are responsible for performing research involving clinical trials. Study Principal Investigators have primary responsibility for NIH-funded studies.
   
   Example: Concise List
   The investigator database includes three types of investigators with different responsibilities:
   
   
   
   • Basic Investigator does basic pre-clinical research
   • Clinical Investigator does research involving clinical trials
   • Study Principal Investigator does research for a specific NIH-funded study
   
   Example: Concise Table
   
   
   Database Listings for Investigators/Responsibilites
   

   Investigator Type	Responsibility
   Basic Investigator	Pre-clinical research
   Clinical Investigator	Clinical trials
   Study Principal Investigator	NIH-funded clinical studi

   
   
7. Write complete, clear sentences.
   Don’t write this: The most prominent need for the Large Hadron Collider is the quest for the origin of the spontaneous symmetry-breaking mechanism in the electroweak sector of the Standard Model (SM), new direct experimental insight is required to advance in one of the most fundamental questions of physics which is closely connected to this, namely: What is the origin of the different particle masses?
   Do write this: We need the Large Hadron Collider to understand the spontaneous symmetry-breaking mechanism in the electroweak sector of the Standard Model (SM).  New experimental insight will help answer a fundamental physics question: What is the origin of the different particle masses?
   
   
8. Use correct spelling and punctuation.
   Techies (and everyone else) should know the most common uses of periods, commas, colons, semicolons, apostrophes, and quotation marks.  Everyone should run spell-check. Techies who are wretched spellers, the kind spell-check can’t always help, should create a personal “cheat sheet” of words they frequently misspell or should identify a colleague who will check anything they write before it’s published.  Of course, spelling and punctuation could be called the technical aspects of writing; perhaps appealing to techies’ respect for accuracy will work?    

• Create a “library” of model documents.  In many cases, a good example is the best teaching tool.
• Publish writing guidelines.  If the communications staff are the only people who have copies of your company’s writing guidelines, you’re wasting a valuable resource.  Don’t get us wrong.  We realize few people, techies or others, actually read the writing guidelines.  But guidelines can help make the revision process more efficient and reduce techies’ perception that they’re being forced to rewrite a document just because the editor is a stickler.  If the guide is long, write a handy, short version featuring the most common issues for techies.
• Create templates for the documents techies commonly write.  Templates protect struggling writers from reinventing the wheel each time they have to produce a document and free them from having to worry about format while they are writing. Templates should include writing prompts. For example, if the template indicates a summary, include a prompt like this:  “Summary should be no longer than 150 words. It should be a digest of entire document, with a brief description of the problem, the steps already taken to solve it, and your recommendation.”
• Help techies focus on readers’ needs.  Distribute our checklist "How Tech-Savvy Is Your Reader?" and ask techies to complete the checklist before they begin writing.