Technical Writing Tips
Yes, I offer writing and editing services, but what if YOU are invited to or are required to do technical writing despite having little or no experience in that arena? These tips are for you!
What’s Different About Technical Writing?
Technical writing is to copywriting as playing the musical scales is to playing a song or a symphony. You don’t get to innovate or be too creative! “Just the facts, Ma-am!”
- Copywriting, like playing a song, evokes emotions. It probably involves story-telling, and it aims to be persuasive.
- Technical writing, like playing the scales, involves perfecting the structure which undergirds all creations that evolve thereafter.
- Put another way, copywriting is more like describing the interior décor, colors, and beautiful landscaping of a home, whereas technical writing equates to describing the design and mechanics of plumbing and electrical systems, weight-bearing beams, and drywall that form the underlying “bones” of that home.
- The Society for Technical Communication (STC) defines technical writing as “the process of gathering information from experts and presenting it to an audience in a clear, easily understandable form.”
- STC also notes: “Today, the field continues to grow and change. Increasingly, content includes visual and graphic information, it is expected to be accessible through multiple devices, and the line between technical documentation and marketing gets blurrier every day.”
Definition and Examples of Technical Writing
Technical writing typically takes the form of a user instruction manual or documentation of policies, procedures, research protocols, or other formal documents – too often gathering dust on a shelf until an emergency arises. Then, people flock in a panic to find the manual and hope they can understand the directions. (We’ll talk about “underlying assumptions” in a minute.)
It is the primary literature in software development, mechanical operations, technical enterprises, medical research and protocols, financial institutions, and in fields of science. Here are common examples:
- Documentation of every step of the underlying processes, formulas, and navigation in the creation of software.
- Documentation of every step of the processes and procedures that are subject to financial, personnel, safety, or another kind of audit by an independent audit company or agency.
- Instruction manuals for assembly of products.
- Policies and Procedures manuals for businesses (these may be combined or in two separate manuals).
- User manuals for the operation of products or systems.
- Analytical reports (such as audits or reviews of a company, a project, a research study, etc.)
- Executive Summaries or other extraction of critical data and information from lengthy documents.
Technical writing presents a number of unique challenges, whether you’re a freelance copywriter or an employee. Here are some ways to approach a technical writing assignment like a pro.
Think First | Write Afterward!
In theory, you will have time to think about a project for a hot minute before you delve into it. (Experience teaches this often is pure fantasy, but I’ll not digress with anecdotes.)
Consider Who the Users Are and What They Need to Accomplish
When people refer to a technical manual, they might be in an emergency situation or time-sensitive situation, such as:
- Needing to learn how to shut off complicated equipment throughout an office complex during a flood.
- Wanting a quick fix, such as how to navigate to the screen that enables them to change a password.
- Struggling through “simple” instructions on how to assembly a baby crib or to learn whether both oil and gasoline are needed to run a motor.
This means they need to find a clear answer quickly. Keep that in mind while composing or editing technical works.
Auditable Documentation
A completely different reason for acquiring excellent technical writing skills is when you are charged with documenting step-by-step procedures to provide evidence of how a company operates in various functions. This information is critical when the company or agency is subject to financial, personnel, or other kinds of audits. Audit findings can result in huge financial penalties and even the closure of a business. Accuracy and thoroughness are mandatory.
Formal and Informal Life-Long Learning
Other people are using a technical document or manual to learn something new. Often, that knowledge is out of their field of expertise, and novices need clear, step-by-step instructions. This means that underlying assumptions must be stated at the beginning, or that there are no unexpressed, underlying assumptions as the instructions are imparted.
Underlying Assumptions
Technical writing requires (but does not always achieve) clear, easily understandable, thorough, and/or extensive documentation in written words. When technicians (in any field) write instructions or documentation of what they did to create the product at hand, they often omit underlying assumptions. After all, the technician may not even realize that there are assumptions involved, because – to him/her – they are as taken for granted as is the air we breathe.
Thus, steps that experts take when going through a process may not be written down, because they come automatically. An analogy is that, when you are driving a vehicle, your hands and arms automatically move the steering wheel this way and that without your thinking about it. Your mind/body is both awareness and muscle trained for the job. But for a novice, who knows nothing about the subject matter, those assumptions and missed steps are unknown and can cause a lot of confusion.
Structure Counts Big Time In Technical Writing
People do not want to sift through data and information that is not directly related to what they need to know NOW! Thus, the structure of your writing should be easily scannable for people who choose to skim. That means putting the title/topic of each section at the top, followed by sub-headings and the details. The easiest way to do that is by using a Table of Contents.
Insert a Comprehensive Table of Contents
and, If Appropriate,
an Index at the End of Your Technical Writing Doc
In keeping with the above concept, utilizing a table of contents will benefit not only your reader, but it also can help keep your material organized and cohesive.
My preference is to use Microsoft Word for composing. Creating a Table of Contents is very easy when you use Headings 1, 2, or 3 within the body of the work. After the text is written, you can simply use the menu to Insert a table of contents, and it will pick up the headings you used and arrange them in order along with the corresponding page number. You can update the table as you add more content.
Options
Remembering who your audience is, what they need, and what you want to emphasize, you might choose among presentations styles, like:
- Chronological Events
- Functions (Specific Tasks or Topics)
- Easy Steps Come First as the Basis for Subsequent More Difficult Maneuvers
- Definitions Followed by Content
- Rules Followed by Content
- Policies Followed by Content
- History of (company / project / task / problem / etc.) Followed by Content
Again, this is the kind of thing best considered and decided upon in the pre-planning stages BEFORE you start to write a single word.
Don’t Be Cute: Get to the Point Immediately
The goal is to enable the reader to understand the topic quickly, clearly, and thoroughly.
- Organize the material as if you were doing an outline.
- List the assumptions at the beginning, if necessary.
- Use bullet points and/or lists when possible.
- Write short sentences.
- Use the fewest words possible.
- Technical writing is not the place in which you want to put “filler” or “fluff.”
- That includes introductory phrases, anecdotes, analogies, and other tools one normally uses in a more conversational and/or persuasive document.
- Omit jargon.
- If you’re writing a technical manual for use by fellow experts in the field, some jargon might be okay.
- If you’re writing that same technical manual for end-users who are not experts in the field, replace jargon and anonyms whenever possible with other, simple language.
- You might also include jargon the user might encounter and give definitions of that commonly-used jargon.
- Apply the following test: write down each technical topic’s goal. When you write content, ensure it meets that goal.
- Include a glossary if your document contains many long, complicated names and terms.
Use Screen Shots and Videos
to Show Computer Navigation and Other Instructions
Design your product by using consistent formatting (headings, sub-headings, font size and type, numbering or bulleting, etc.). Design sections consistently. You may use color coding for certain types of information, summaries, or questions. You could utilize call-out boxes to separate large sections of text. To simplify concepts, you might create charts and infographics to display data.
Of course, if you’re holding a training session with your technical writing content, you also can use MY (Nancy’s Novelty Infographics) to announce breaks, breakout sessions, and more. Chirp! Chirp! I just thought I’d throw that in here in case you were unaware of those offerings.
Create a Cover Page
Many documents are available only online these days. However, if the document will be printed, you can make it the most professional-looking by creating a cover page. If the recipient also wants it to be in a binder, print the cover page to insert beneath the plastic shield on the binder and copy the title, author, and any other pertinent information in landscape mode, so that you can print it and cut it to fit the spine of the binder. This makes it easy to find on a shelf, and the recipient will be grateful for that extra step.
Questions?
Feel free to contact me with questions or to book me for your writing project. Email MyPersuasivePresentations@gmail.com and put “Writing/Editing Consultation” in the subject line. Remember, I offer a FREE 15 – 30 minute initial consultation.
Do It The Write Way! Let My Fingers Do Your Talking!