Please consider a donation to help fund Vision: A Resource for Writers
Table of Contents
Technical Writing Hints
By Patrick M. Kennedy
Copyright © 2010, Patrick M. Kennedy, All Rights Reserved
Attitude and Approach
It is best to work with the reader, not against the reader. The quicker the reader can understand what is written, the more effective it is.
Write specific rather than general information. Technical readers are usually interested in detailed information, such as, fact, figures, conclusions, recommendations, and especially how to do it, but make it to the point. Too many facts and figures within a paragraph can lose clarity, but placed in a table or a bullet list they become easier to read. Even listing them within a paragraph by, (1) numbering the separate items, (2) putting the numbers in parentheses to separate them and make them easier to remember and, (3) putting them in a logical sequence, is a common approach. Recommendations and How-To-Do-It copy can be easier to follow if they are in numbered or bulleted lists. Sometimes using a check-box square in place of a number or a bullet can give the impression that each step should be read and checked off, even if only mentally.
Write in a clear style, not chatty as a personal letter, but kept simple, direct, expressing the point, and relaxed yet professional.
Use the active voice rather than the passive voice. Action is expressed directly rather than indirectly. ‘Do the act’ rather than ‘the act was done’. Example: ‘Pat tested the program’, rather than, ‘The program was tested by Pat’.
Use jargon (the technical terminology or characteristic idiom of a special activity or group) sparingly. Technical terms and words are helpful shorthand when addressing the documentation to readers within the profession, but may confuse readers who do not have that special background. The word ‘yield’ can mean ‘the amount or quantity produced’ to an engineer, but ‘slow down’ to the driver of a car or truck. Use legitimate technical terms when they communicate the meaning and ideas clearly, but not because they sound impressive. Avoid big, important-sounding words that can be replaced with simple words that mean the same thing. In other words, speak plain English.
If jargons and those rare words must be used, consider a footnote or glossary of terms (or even a brief definition in parentheses) to keep the reader from diving for the dictionary every few minutes. This also helps the reader keep a focus on the subject.
Refer to the sections: 1.2 Know The Reader, and 1.6 Clarity.
It is best to be to the point and communicate the information in as few words as possible. Do not take up too much of the reader’s time; avoid redundancies (a needless form of wordiness in which a modifier repeats an idea already contained within the word being modified). In other words, say it once.
Be consistent in the use of numbers, hyphens, and units of measure, punctuation, equations, grammar, symbols, capitalization, technical terms, acronyms and abbreviations. This creates a comfortable zone for the reader and avoids confusion.
Define acronyms after the first use or as soon as possible in the document (or for larger documents define it again in another section). Do not assume the reader will know what they mean. If the definition of a word or terminology could possibly be unclear, define it in one way or another, i.e., index, footnote, or parenthesis. Certain sections of large documents may be separated for other uses in other documentation, so the definitions should be carried with it.
Break the writing into short sections and paragraphs to make it easier to read. Starting with an outline is a great start. The outline can directly reflect the headings and sub-headings in the order the information are being presented. If you are working with separate special material experts (SMEs) for each section, they can be assigned by heading for their input.
Notice this article is laid out in the most common technical document format: Heading 1, Heading 2, and so forth, to illustrate the use of sections and paragraphs to format for clarity. (Note: Never use the abbreviation ‘etc.’ or similar abbreviations in technical writing because it implies there is more than meets the eye or something is inconclusive, and this can lead to confusion).
In the same way, short sentences are easier to read and hold the readers attention rather than long, drawn-out, wordy, overly comma separated, strings of words like this one.
Using visuals, (drawings, photographs, maps, graphs, pie charts, bar charts, tables, and schematic diagrams) reinforce the text and make technical communication more effective.
Persuasiveness is the ability to move by argument, entreaty, or reason to a belief, position, or course of action. In technical writing the persuasiveness comes mostly from the confident and knowledgeable voice of the writer. Be direct and do not ask questions unless there are answers. Illustrations and past examples can help persuade and assure the reader the information is correct. Two plus two equals four. See! It works every time. Assure the reader it is as easy as that.
The technical depth is directly related to the prospective readers. Know the reader and write to that technical depth. Everything that is available on the subject should be covered in the document, or referenced to another available source. A bibliography or index can help here. A separate section with a list of special definitions and acronyms within the document is a big help.
Know the Medium, the Final Product
Some of the final products of technical writing are standard documentation, web content or design, computer-based training, software manuals, hardware manuals, online help systems, and marketing material for high-tech products, to name some.
The technical writing process is a simple expansion of common writing and editing practices combined with organization and research. Working with others, especially an editor or another writer is a plus for accuracy. Developing and maintaining certain standards and definitions at the beginning of a document creates consistency. Creating an outline or even a flowchart of the process you are writing about helps in the organization. Charts and tables developed before writing can help researching the required information. Starting with a pre-defined document template makes it easier to organize and format the information.
Keeping it simple and preplanning are the keys to a successful document. Review, review and review, by yourself and with others, are the three essential elements in writing any document.
Words like winter snowflakes