Part II: What Is Technical Writing? Precision, concision, and structure
By Patrick M. Kennedy
Tech writing requires not taking up too much of the reader's time with wordiness.
In Part I, I discussed the general qualities of technical writing. In Part II, I'll discuss more specific requirements of this type of writing as well as the knowledge and educational requirements commonly sought after in technical writing opportunities.
Word choice is important. 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 without that special background. Use legitimate technical terms to communicate meaning and ideas clearly, but not because they sound impressive. Avoid important-sounding words if simple words that mean the same thing exist. In other words, speak plain English.
Write to the point and communicate the information in as few words as possible. Don't take up too much of the reader's time and avoid redundancies or wordiness. In other words, say it once, clearly. Be consistent in style in using numbers, hyphens, punctuation, equations, grammar, symbols, capitalization, technical terms, acronyms, abbreviations, and units of measure. This creates a comfort 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 following sections). Do not assume the reader will know what is meant. If the definition of a word or terminology could possibly be unclear, define it in an index, footnote, or in parentheses. Certain sections of larger documents are often separated for use in other documentation, so the definitions should be available within each section.
Break the writing into short sections and paragraphs for easier reading. Creating an outline is a great start; it can directly reflect the headings and sub-headings in the order the information will be presented. If you work with separate SMEs (subject matter experts) for each section, they should be assigned by heading for their input. Short sentences are also 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) reinforces the text and makes technical communication more effective. The technical writer must learn to use some basic graphics programs or work with a graphic artist. Generally, it is more time efficient for writers to create the graphics themselves.
Get your documentation reviewed. Peer review is one of the most important processes. Everyone who has contributed to the input must review the documentation, or at least the section or information they contributed. All changes should be reviewed after they are made. Management review usually comes after the document is finished, adding a signature of approval.
The technical writing process is a simple expansion of common writing and editing practices combined with organization and research. Standards and definitions should be developed at the beginning of the documentation process and then maintained throughout to create consistency. Creating outlines and flowcharts for information and procedures helps to organize unfamiliar material. Developing charts and tables before writing can indicate wholes in the information and be helpful during the research and information gathering phase. Starting with a pre-defined document template or style sheet is a great way to organize and format the information in a consistent and user-friendly way.
The technical side of being a technical writer can be quite complex, depending on the particular technology to be documented. The successful technical writer must not only have a command of the English language, but also must be proficient in some of the following user applications: MS Office Suite, Adobe FrameMaker, Adobe PageMaker, EMC Documentum, Macromedia RoboHelp, Microsoft Visio, Adobe Photoshop, Adobe Illustrator, and many more. In addition, the technical writer may be asked to know programming languages such as, HTML, C+, C++, SGML, UNIX, XML, JAVA, or any number of specialized programs related to the particular job.
Qualifying education might be a degree in English or Technical Writing, or sometimes the job requirement is a degree in Engineering, Computer Sciences, or even Marketing. The opportunities in the technical writing are many, but the qualifications and processes are varied and intense.
Patrick M. Kennedy has been a professional writer/editor/graphic artist for 30 years. He has published a novel, short stories and poems, articles in magazines, and he contributes a regular lighthearted column to the Senior Wire News Service. Find more about his background, writing samples, and services at:www.abetterword.com