Technical Writing Basics. This article is not intended to replace a full Technical Writing course. It is offered as a quick and dirty guide outlining the basic techniques and styles used within the technical writing field for people who do not normally write technical documents.

For clarity and ease of use I am breaking this information into 5 articles that cover the basic techniques used in Technical Writing including:

• Knowing Your Audience

• Top Down Structure

• Writing Clear Sentences

• Being Concise

• Using the Active Voice

Knowing Your Audience

Before ever touching the keyboard or starting to do research, a technical writer must know for whom they are writing. This is not simply a matter of saying I’m writing for the end user, but rather, having a thorough understanding of who will use the document and why.

When defining who the audience is going to be, you must consider the following points:

• Who and What Level

• Purpose of the Document

• Context

• Organization of the Document

Who and What Level

Who are you writing for? That is your first question. By knowing who the audience is, you can immediately start to tailor the information accordingly.

A How To Guide for a general contractor, would include much less background information than a How To Guide for the average home owner.

If you are writing an Operation Manual for an X-Ray Machine and the end user is an X-Ray technician, you know that there will be a solid base of general knowledge and general theory.

If you are writing that same manual for someone who does not use the machine everyday, then steps that the technician would consider “given” must be included in the manual.

Purpose of the Document In technical writing, there are three reasons to write a document:

1. To inform:

When writing to inform, the writer must convey the required information as quickly and as concisely as possible. Knowing the target audience helps you decide what information is required.

2. To complete a task:

The user of this type of document wants to complete a task as efficiently as possible and will not want to know any background information. Repeated reference to the document is expected.

3. To teach a skill:

Teaching a skill means that the end user must have a strong understanding of not only the actions required but the reasons for them and any other relevant back ground information. Again what is relevant can be determined by knowing the audience. After reading this document the end user is able to perform that task with little or no reference to the document.

Determine which of these three your document is going to accomplish.

Context

Always put the document into a context for the end user. Let them know why they should read the document and what they will get out of the reading. They are more likely to actually read the document if they know what is in it for them. Let’s face it, very few people read technical manuals for fun.

Organization of the Document

Organization of the document refers to the physical layout of the document. The order the information is presented can change the usability of the document. There are many different ways to order the information and here are only a few examples:

Chronologically

Order of the tasks to be performed

Order the information appears in the product itself

One layout might be fine for someone try to perform a specific task within a software suite but might cause anger and frustration in a user trying to perform a different type of task.

For example:

A computer user is directed to location “A” within the software. They are then directed to location “B”, location “C” and then back to location “A”. Transiting between locations within the software is a matter of clicking with a mouse.

The same layout for a technician that is trying to shutdown equipment, physically spread out over four different locations, will not work. The technician will become frustrated with the manual and stop using it, potentially missing steps and/or important information.

Ensure that the organization is appropriate for the target audience, one size does not fit all.

ConclusionAny tech writer knows that knowing your audience is the first thing they must do before ever touching the keyboard, starting the research or interviewing a subject matter expert. This is the first and one of the most important steps in technical writing.

In the next article, I will discuss what Top Down Structure is and why it is important in technical writing.