In this article you will learn

• the importance of writing in the technical workplace
• the attributes of technical writing
• why technical people need technical writing
• the beginnings of the writing process.

The need to make the world a better place and build solutions that are beneficial to the human race is perhaps the biggest reason to choose a technical field. Perhaps you are thinking of building the next facebook or twitter, perhaps you are thinking of developing medical technologies or mechanical systems. Maybe you have a better idea for a boomerang. In any case, seeing your solution come to life and grant wishes in the real world is of great appeal as a technician. What you probably don't want to do is write about it.

Unfortunately, there's just no avoiding writing in the technical workplace because you will never work in perfect isolation, and where there's a need to communicate, there's a need to write.

However, if writing was not your strong suit in high school and if literature and romantic poetry are not among your passions, don't despair. Technical writing is a simple, stripped-down tool designed to get the job done, and the job is to convey information to people who need it. It's not meant to be fancy. It's meant to be clear and effective.

Not that writing well is easy. But it doesn't require a natural gift for wordplay or perfect linguistic pitch. Like any craft, it requires discipline, conscious effort, and some practice.

Whether you are designing a building, an electrical system, or a hydraulic system; whether you are coding software, designing websites, or creating a user interface, you do not rely on inspiration or make sacrifices to the gods. Rather, you work according to a set procedure, following guidelines and rules, using previous designs as a launching point. You focus on usability and practicality; you don't add needless embellishments or take poetic licence.

The most elegant solutions are invariably the simplest.

There's another reason you'll find it easy to learn to communicate well in writing: you already know how communication works; you speak to people much of the day; you read magazine articles, newspapers, blogs and websites. You know what works; you know what sounds good and what doesn't, what creates clarity and what gets in the way. Now you just need to develop the habit of thinking like a reader and always asking yourself, "Would this be clear to me if I came across it for the first time and didn't already know what it meant to say?"

Attributes of Technical Writing

Documents are tools used to convey specific information, and like any tool they need to be uniquely fashioned to achieve their specific purpose. However, they must always be:

• Clear : they must be understood by readers on first reading, without any ambiguity or possibility of misunderstanding.
• Complete : they need to provide all the information the reader will need in order to understand the situation and the required follow-up.
• Concise : they need to be as brief as possible while remaining clear and complete. The more words you use, the longer it takes to read and the more verbiage there is in which readers my lose their way.
• Accessible : they should be organized and formatted so that readers can find the specific information they require without having to read the entire document.
• Correct : they should be free of grammatical and mechanical errors. Grammatical errors can lead to misunderstandings and will make you look unprofessional.
• Accurate : they must not contain any factual errors. Factual errors will make you look not just unprofessional, but incompetent.

The Writing Process

In any writing situation, whether your document is short or long, formal or not, you should begin by thinking about what you hope to achieve with your document, it's purpose and to whom you are writing, the reader.

Determine the Purpose

If you need to accomplish something by writing, be absolutely clear on what it is you hope to accomplish. Generally, you're trying to inform readers or trying to get them to do something. Often we combine these goals, as when you inform someone of an incident or circumstance and then request an action or an authorization for an action in response.

"If you can't explain it simply, you don't understand it well enough."
-- Albert Einstein

Consider the Audience

The audience is the person or people to whom you're writing. If the audience is intimately familiar with the details of your project, you won't have to provide as much context. If the audience is a fellow techie, you won't have to define your terms. However, if your audience is a budget-conscious accountant with no technical understanding of what you do, you may have to do more.

This is how audience and purpose define the content of documents. Ask yourself before you start what your particular readers will need to know and need to be told so that they understand what you're saying and will agree to what you're asking.

Brainstorm the Content

With your purpose and audience clearly in mind, next is brainstorming. Simply jot down all the information that may be relevant and useful to your readers. Just put down ideas and elaborate on them a little, whether you are using brainstorming apps, word-processing software, or even the back of an envelope at this stage.

Organize the Content

Once you're satisfied that you've identified all the information that you'll need, begin organizing it. You don't need to rewrite it; save yourself some time by just numbering the items you've already written and drawing lines to connect them. Group the information into a specific sequence of categories. And there are two ways of thinking about this. You can think of your documents as one-way conversations with your readers or as stories you tell your readers.

Determine the Correct Writing Style

You've analyzed your audience and, based on that analysis and the purpose of the document, you have decided what content should be included. Now go one step further. Different audiences require different writing styles.

Write the First Draft

Once you have a clear outline, you already know what you're going to say and in what order you're going to say it (like speech notes). And if we think of correspondence as a one-way conversation, then imagine yourself sitting across the desk from your reader, take a deep breath, and say what you would in person. But type.

Don't stop to second-guess yourself or you'll lose the thread. Don't bother to edit your sentences, to crack open a thesaurus, or to tweak your grammar. Just write.

You know how to speak. You make yourself understood in conversation all the time. So, just string together the ideas you already have on the screen in front of you, with no of judgment. This will give you a good, fluid first draft. Imagining yourself speaking to the reader should also help you set the proper tone.

Revise in Stages

When revising your first draft, do it in the following stages, focusing on one type of revision at a time. In this sequence, we start with the large adjustments and make increasingly finer ones.

1. Substantive editing : First, adjust and reorganize the content to make sure your document contains the right information in the proper sequence. If in reviewing your first draft you find that the content is not organized as logically as it should be or that it omits information necessary to craft a full argument, reorganize the content and fill in the gaps. Conversely, if you find that some information doesn't advance the purpose of the document, delete it or put it into a separate document with a different purpose. If you often find yourself editing and moving content after your first draft, you may want to take more time at the planning stage.

   Remember: knowledge stuck in your head is no good to anyone else. Always think about how to make things perfectly clear to your readers.

2. Stylistic editing : Only now that you have the proper information in its proper sequence, should you edit for style and tone. There's no point agonizing about the precise phrasing of an idea or the perfect transition between two sentences until you're sure that you won't be moving the information or sentences around later. What is moved generally has to be re-edited and you'll have wasted time. But once sentences are organized, you should make your document sound good when read aloud and create a tone appropriate for the reader.
3. Copy editing : Only when you've settled on exactly how your sentences will read should you worry about grammar and mechanics. There's no point in agonizing over the punctuation of sentence that you are going to change for stylistic reasons later or looking up the tricky spelling of a word you are going to replace with an easier one. By the same token, it is only at this point that you should worry about the mechanics of your document, things such as the proper abbreviations and capitalization, accurate use of units of measurement, and so on. These are important in signalling attention to detail and respect for form, and they enhance the professionalism of the document. However, unless the rest of the document works well, these elements are mere window dressing.

   Depending on the kind of document you are producing, you may also have to double-check your references and citations, provide a glossary, and the like.

4. Proofreading: In the professional world, you will generally use a corporate or organizational template that defines how your documents will be formatted and sets up things like the page margins, headers and footers, and so on, for you. Once the document is formatted, review it for errors in layout--mislabeled headings, misaligned paragraphs, misplaced figures, and missing headers or footers---as well as for any uncaught typos and last-minute fine tuning.

In a sense, you now know pretty much all the basic concepts of technical writing. All that remains is practice. Congratulations: you're on your way to becoming a competent technical writer.