Introduction

The primary reason technical engineers and programmers write a poor technical document is because they have had no training or experience in that field. This is not unusual. They have other responsibilities and training. Here we will address some of the basics to becoming a better technical writer by covering the most common problems that are encountered: Then describe how to avoid them or improve upon them. The following is not intended to be an instructional manual because it will only scrape the surface. It is meant to assist first-time or once-in-a-while technical writers.

The following hints and discussion is written in the format of a standard technical document as a self-illustrating example. The following sections are general areas to consider in developing good habits and results before undertaking the technical writing process.

Know the Reader

It should be known if the reader, or end user, is an engineer or any other professional who will be fundamentally familiar with the subject of the technical document, e.g., a manager; a technician; a student or high-end user; or a layperson reading for information only. This is something that must be determined before the writing begins in order to decide on the technical depth, word choices, and attitude of the writing. It is also necessary so information is not written down to the professional, or over the head of the layperson.

Know the end task of the reader. Is it for?

• Information only



• Building or using a product



• Learning a process



• Testing or validating a process or application



• Examining complicated details or figures



• Using an application or process



• Maintenance or repair



• Part of an overall document set

In knowing the end task of the reader, the information can be presented and detailed accordingly.

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.

Style

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’.

Word Choice

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.

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.

Format

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

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.

Technical Depth

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.

• Standard documentation can involve writing a lot of detail and explanation, including graphics and references.



• Web content must be brief, direct, to the point within a few words, and in a limited screen area. Much like advertising copy, the web page must sell itself at the first glance or the readers will move to the next page as fast as a mouse click, and you have lost them.



• Software and hardware manuals contain a great deal of detail and the most important focus for the technical writer is that the detail must be well organized. Keeping the common chunks of information together and in the proper order will keep the reader involved and better informed. Refer to the above section 1.7 Format.



• Online help systems are a combination of the web page and the manual standards. There is a great deal of detail, but it must be in brief and focused statements. Each statement or paragraph must stand on its own because the normal process of moving from link to link in a help file will force their detachment from the previous paragraph, thus, it must speak for itself.



• Writing marketing material for high-tech products must be a combination of all of the above with the over-riding aura of a sales pitch tying it all together. Photos and graphics are usually used in marketing materials. Write the copy so it stands on its own. Do not describe the colors because they are in the photo; do not go over the numbers because they are in the graph; but explain why the colors and numbers should be on the reader’s desk or in their business.

Summary

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.