Happy’s Essential Skills: Technical Writing
Technical writing is one of those topics that they don’t really talk about in college—at least not where I went. Writing and English has never been a strong like of mine compared to science and math. So I did my required time in English and wrote my lab reports the best I knew how. Even my senior projects and graduate reports were mostly graphs, tables, figures and drawings and the necessary information to explain what they were.
After taking my first job with Hewlett-Packard, it took me only a year to realize one startling fact: Only the bosses get to go to conferences! Junior engineers don’t get to go to conferences. But I wanted to learn more, meet other engineers in printed circuit manufacturing, see the latest equipment and listen to technical papers about my new field. Then I discovered the secret solution: If I presented a technical paper, the company was happy to send me to the conference.
I set out to write my first technical paper and discovered the process of technical writing and company legal reviews. I presented my first paper on our automated plating project at NEPCON in Anaheim in 1971. All went very well—and I decided that I would write a technical paper every other year. That went well for a while, but then I was writing a technical paper every year, then two or three a year for magazines, and soon marketing was asking me to write five or six each year, since I was writing a lot about HP hardware and software. This progressed over the next 40 years to columns, blogs, book chapters and eventually, an entire book.
Figure 1: General overview of technical writing applications.
Why is Technical Writing Important?
Technical writing consists of straightforward, easy to understand explanations and/or instructions dealing with a particular subject. It is an efficient and clear way of explaining something and how it works. An author writes about a particular subject that requires directions, instructions, or explanations. Technical writing has a very different purpose and is comprised of different characteristics than other types of writing, such as creative, academic or business.
The subject of technical writing can be one of two things:
- Tangible: Something that can be seen or touched (e.g., a computer or software program, or how to assemble a piece of furniture).
- Abstract: Something that involves a series of steps unrelated to a tangible object (e.g., steps required to complete a laboratory process).
Some examples of technical writing include:
- Technical papers
- Instruction manuals
- Policy manuals
- Memos
- Grants
- White papers
- Process manuals
- User manuals
- Reports of analysis
- Instructions for assembling a product
Writing Processes
I believe that it is always good to have a process, and technical writing is a perfect fit for that. Some of the problem solving processes discussed in previous installments of this series are useful, like the scientific method. But all processes start with an idea or even just a thought like, “What are you going to write about?”
Figure 2: General technical writing process.
Mind-Mapping
A mind map is defined by Wikipedia as “a diagram used to visually organize information. A mind map is often created around a single concept, drawn as an image in the center of a blank landscape page, to which associated representations of ideas such as images, words and parts of words are added. Major ideas are connected directly to the central concept, and other ideas branch out from those.” Figure 3 shows a typical Wikipedia mind map.
For any form of topic organization, I find that being able to see it arranged graphically is very helpful, and would strongly recommend the mind-mapping approach. It's also brilliant for taking notes at meetings—I've even projected notes while the meeting was taking place, so that everyone could see what they had said and its context!
This method is illustrated in Figures 4 and 5, in which a simple mind map is built on the topic of stencil printing variables. In the most complete version, some of the groupings and causal linkages have been drawn and appropriate notes have been added.
Figure 3: Wikipedia mind map of typical guidelines.
Figure 4: Stages in the evolution of mind-map notes.
Mind maps are considered to be a type of spider diagram. A similar concept is brainstorming. Brainstorming will be covered in an upcoming column.
Happy’s Process for Technical Writing
Following is my process for technical writing—I hope that it will be useful to you. My process is the outgrowth of doing daily tasks. Generally, it follows these steps:
- Create a detailed outline of a topic.
- Make Powerpoint slides for a verbal presentation.
- Make the verbal presentation using your Powerpoint slides (this is important; you must actually speak the words).
- Using your outline and the Powerpoint slides, pick five to 12 slides that will become your figures in a written paper.
- Using the Powerpoint slides, begin writing a narrative, keeping the words you have already spoken in mind.
- If your slides contained bullets, data, etc., add tables and bullets until you come to one of the figures you have selected
- Add the figure(s) and continue until all your Powerpoint slides are consumed.
- Re-read what you have written, making sure that thoughts are complete and the subjects flow.
- You could record step 3 and play it back or use voice-to-text software for step 5.
Figure 5: Relationships and comments added to the mind map.
I have collected a series of technical papers or articles to create a three-hour technical course. Two or three technical courses can become a Chapter in a book. As you can see, I sneak up on technical writing; I cannot sit down and do it from scratch!
University of Michigan’s Technical Writing Guide
The Univ. of Michigan’s Technical Writing Guide is a comprehensive, 61-page instruction manual for technical writing. The five sections and eight appendices explain topics that range from general grammar and punctuation instructions, to incorporating lab reports, completing theoretical analyses, constructing reference sections and more. It’s a beginning-to-end guide that anyone attempting to generate a piece of technical writing should bookmark and refer to often.
MIT’s Technical Writing Process
Another useful reference is a compilation of lectures on technical writing by the MIT Writing Center. Following is a portion of an outline of 24 Powerpoint slides entitled, “Sentence Structure of Technical Writing,” written by Nicole Kelley.
1. Good Tech Writers Practice
a. Planning – before you begin
i. Know your audience and expectations
b. Clarity – avoid jargon and unfamiliar terms
i. Audience familiarity with the topic determines appropriate use of jargon and TLAs
c. Brevity – use words efficiently – never use two words when one word will do
i. Pare your language down to the essential message
ii. Place key information first in the main clause
iii. Remove redundancy by combining overlapping sentences
d. Simplicity – for clarity, balance details wisely with audience needs
i. Many engineers want to provide as much specific detail as possible, but this can come at the expense of reader understanding and your main point. Choose words with clear meanings
e. Good word choice – Avoid too many abstract nouns and unnecessary words.
i. Order the words in your sentences to avoid ambiguity
f. Active voice – an active voice is more straightforward and stronger than a passive voice
i. When in doubt, read passages out loud to determine the natural sound
g. Committing to writing as a process – good writing doesn’t happen overnight; it requires planning, drafting, rereading, revising, and editing
i. Learning and improving requires self-review, peer-review, subject-matter expert feedback, and practice
h. There are no shortcuts—practice makes perfect. Good writing is a habit that takes time to develop.
Good Advice
Regardless of the type of document that is being written, technical writing requires the writer to follow the practices of knowing his audience, writing in a clear, non-personal style, and doing extensive research on the topic. These practices enable the writer to create clear instructions and explanations.
- Know your audience. An expert in the field will understand certain abbreviations, acronyms, and lingo that directly applies to such a field. A novice will not understand in the same manner, and therefore, every detail must be explained.
- Omit opinions. Use an impersonal style. Write from a third person perspective, like a teacher instructing a student.
- Presentational strategies help the readers to grasp messages quickly.
Four points to keep in mind:
- The writing should be as straightforward as possible in order to ensure the reader understands the process or instruction. This may be simply a list of steps to achieving a desired goal, or a short or lengthy explanation of a concept or abstract idea.
- Know how to research for your intended audience. Gather information from a number of reliable sources, understand the information gathered so that it can be analyzed thoroughly, and then put the information into an easily digestible format to instruct those who read it. The more inexperienced your audience, the more information you will need to gather and explain.
- Be thorough in description and provide enough detail to make your points, but use an economy of words and avoid using gratuitous details.
- The top-down strategy (tell them what you will say, then say it)
- Headings (like headlines in newspapers)
- Chucks (short paragraphs)
- Plain, objective style so that readers can easily grasp details.
A good technical writer can make a difficult task easy and can quickly explain a complex piece of information.
Further Reading
The University of Michigan Technical Writing Guide includes a reference section with additional documents that you can download. This is true also of the MIT Technical Writing link provided above.
Conclusion
Are you ready to try your first technical paper? It’s not as difficult as you may think, and once started, can do your career a whole lot of good. Soon, IPC just issued a call for papers for next year’s APEX EXPO in San Diego. This is true also for the SMTA conference next fall in Chicago. Or, if you would like to submit a technical article for consideration in an I-Connect007 publication, contact Patty Goldman.
