On technical writing

This post is for Dave over at WhatHeSaid.ca and YukonDude.com, because he asked.

I learned technical writing at Nortel Networks where I wrote customer information manuals for the DMS-100, the Passport 7K, and other documents for engineering teams (like AMA billing requirements and ISUP technical specifications).  The most important lessons I learned were:

• Know the product
• Know your audience
• Organize your information
• Know the English language

First, while I have your attention, I would just like to say that I think many (almost too many) organizations underestimate the value of documentation. Other than the product itself, documentation is the only part of the product a customer sees. It makes an impression–not only on your customers, but on your customer support team, your product test groups, any new employee, your marketing department, product management, and I’m sure there are more that I’m not thinking of right now.

I will refer to my first technical writing contract at Nortel as anecdotal evidence. Helen Borodalyuk hired me to address XXX line items in the product information suite for DMS-100 switch for NTT (a telecommunications service provider in Japan). They judged the quality of the code and the quality of the product based on the quality of the documentation. Something I still tend to do. I guess first impressions are lasting impressions.

Regardless, everybody benefits from having accurate, succinct, and complete documentation. I believe good product documentation makes a company scalable. Leading technology companies (Google, for example) also make great multimedia content. In today’s world, I believe good documentation is more than a PDF.

Anyway, I’ll get off my soapbox. Without further ado, here are a few more words on my lessons learned as a technical writer.

KNOW YOUR PRODUCT
Use your product you are documenting. Learn it inside out (engineering perspective) and document it from the outside in (user perspective). For example, if you were writing the procedures to install a telecommunications networking product. Find out how the product is shipped. Take it out of its packaging. Start putting it together. What do you do first? What do you next? What do you do after that? Document every step along the way.

Basically, learn by doing. Systematically document every action. Teach your user how to use the product. Determine what tasks they need to do to make the product work. Describe the task and document the procedures.

KNOW YOUR AUDIENCE

The purpose of technical writing is to teach your audience something about the product. Imagine your audience has a grade 8 level education.

If you have an audience who doesn’t speak English (or the language you are writing in), imagine that they might need a dictionary to translate or define words. Use Simplified English writing rules (below).

Know the main tasks of your audience. Know if they are marketing users or maintenance users. Know if they are technicians or trainers. Know exactly who your primary audience is. Write your documents as if you were talking directly to them.

ORGANIZE YOUR INFORMATION
There is a whole discipline around organizing information. Information architecture. Information design. The buzz word in the late 90s was “information mapping”. Whatever it is now, just know that you have to organize your information to present it in digestible pieces to your reader. My personal philosophy is: “Write so they don’t have to read what you have written.” I think that is a direct quote from Robert Horn. But basically, readers of user guides and manuals have a specific task in mind when they are looking at your information. Present your information so it makes it really easy for a reader to find exactly what they are looking for.

There is a lot of value in information architecture (done correctly). A valuable architect would be able to define the required information about the product for all audience types and be able to build a information framework (architecture, library, whatever you are going to call it). The right publishing system (and person) could dynamically produce predefined information depending the audience and their requirements. For example, you can use product descriptions in marketing collateral and in hardware guides. One piece of content: two audiences. I actually have an information model I developed specifically for telecommunications equipment. But I believe it would work for many products.

Also, do you know how a reader digests information? I have this formula: one third audio (or text), one third visual (pictures, diagrams), one third practical (engagement, procedures, and practical examples). Any one person prefers any two of those formats. If you present your information in all three formats, you will reach a greater audience AND a greater part of your audience will retain what you have documented. Use graphics or other media whenever and where ever possible.

That formula also translates to finding information on the web. On the internet, this world of accessible information, there is a rule: four clicks and the user should find the information they are looking for. The four-click rule also translates to product information suites and to user interface design regardless of the platform (computer software, mobile devices).

KNOW THE ENGLISH LANGUAGE

You are not a creative writer. You are a technical writer. There is a difference. Being a technical writer is a lot like being a journalist. Investigative reporting–actually. You are researching, investigating, interviewing, putting facts (systems, software, solutions) holistically together, and presenting digestible information.

One of my most powerful tool for technical writing is simplified English. According to Wikipedia: Simplified English is a subset of English grammatical rules that was developed by the aerospace industry and is now officially known as ASD-STE100 Simplified Technical English (STE).

Keep the simplified writing rules (below) in mind for every sentence you write. Check. Recheck. And check again.

SIMPLIFIED ENGLISH WRITING RULES AS I REMEMBER THEM

• Only use words that are in a dictionary and can be translated
• Use active voice
• Use present tense
• Create sentences with 21 words or less
• Create simple sentences: one noun, one verb
• Create short, visual paragraphs
• Use parallel lists
• Use positive statements
• Be gender neutral
• Avoid conditional tenses (could, should, would)
• Avoid slang and jargon
• Avoid gerunds at the beginning of sentences
• Create procedures with 10 primary steps or less

If you wanted to start somewhere with this Simplified English style, definitely check out  that standard. ASD-STE100 Simplified Technical English (STE). It takes practice and a good editor to become proficient. But it is definitely worth it.

Did that help you Dave? Was that the type of info you were looking for?  If  I didn’t bore you too much, here are a few more thoughts.

PROCEDURES
Procedures achieve tasks. Figure out what tasks your audience needs to achieve. Perform the tasks yourself. What do you do first? What do you do next? What do you do after that? What makes the most sense — from the user’s perspective?

Ideally, tasks shouldn’t be longer than 10 primary steps. Write sequential steps as separate sentences. Use a primary step to state the action. Use sub steps to describe specifically how to achieve the action.

Test your procedures. Ideally, have someone test them for you.

REFERENCE GUIDES

Reference documents provide dictionary-type information on any user-provisioned variable in the system. My formula for documenting reference manuals was:

• Name the parameter.
• Define the parameter. Where is it? What does it do? Why is it configurable? If it’s an operational parameter, why is it there?
• List the possible values in the parameter. Define each value. Document the purpose of the value and it’s effect on any other parameters in system. Describe the dependencies?

(If anything, documenting a reference guide is the single most exhaustive technical writing task I have ever done. But, in the end, I knew the system inside and out. 🙂

EDITORS

If you can afford one, editors are invaluable. Find a good one. Work with them. You will become a better writer.

STYLE GUIDES

If you can’t afford an editor AND if there is more than one writer for the product, agree on a style guide so you don’t have to argue about init caps in titles or what to do with a semi-colon. (My advice…ditch the semi colon. Use a period and a new sentence. You get 21 more words. :-). My bible has been the Chicago Manual of Style. It’s a complete and widely used reference for style. Sun Microsystems also put out a good style guide called: Read Me First.

MY BOOKSHELF

My bookshelf includes the following titles. I refer to them incessantly:

• Chicago Manual of Style, University of Chicago Press
• Read Me First, Sun Technical Publications
• Don’t Make Me Think, Steve Krug
• About Face, Alan Cooper
• User and Task Analysis for Interface Design, JoAnn T. Hackos PhD (Author), Janice C. Redish
• Information Architecture, Peter Morville and Louis Rosenfeld
• Communicating Design, Dan Brown
• more…

Anyway. That’s what I have today. If I think of anything else, I’ll let you know.

~~~~~~~~~~~~~~~~~~~~~~~

PS: I didn’t just work at Nortel. You can view an online version of my resume at 9068Creative.com.