Technical Writing
From TCPwiki
From Main Page
|
The art or science of explaining technical material.
Contents
Technical writing, a subset of technical communication, is a broad term used to describe specialized correspondence. Technical writing communicates technical (specialized) information that may be printed or printable documentation such as PDF or online help.
The type and form of the produced documentation depends on the needs of the audience and on the documented product. A software application, for example, is usually documented in the form of online help. Online help includes instructions that describe how to:
- Navigate through the application
- Use the application to perform common tasks (workflow)
- Understand each screen in the application and fill out the fields in each screen
Other documentation is always delivered in printed or printable form. Disaster recovery procedures, for example, are delivered to the user in printed or printable form because it is assumed that these instructions are only required when a computer system fails (is no longer on line). In such a situation, online documentation would be useless.
Primary Considerations of Technical Writing
As with any writing, technical writers must understand their audience and the purpose of a particular document. If the medium does not communicate the information intended (i.e., what is trying to be conveyed to the audience) then the communication is meaningless. The goal of technical writing is to translate technical ideas into words that the intended audience will understand. Audience analysis is thus a key feature of all technical writing.
Other Key Considerations
Format, organization, and style are important in that they make information easy for the reader to follow. Information should be available only if the intended reader will need it, and ideally should be available just as the reader needs it. For example, something intended for the general public should have a much greater emphasis on speaking in "layman's terms" than a document intended for a primary audience of people who are already technically skilled to some degree in the field.
Format and style also recognize that some types of data naturally have a superior format: for example, a "how-to" manual for working with machines will have a greater need for diagrams and illustrations, and tables of numbers have a relatively poor ability to communicate overall quantitative relationships for the average reader, than do graphs and charts. Although technical writing formally deals only with the written part of technical communication, it must make proper allowances for non-verbal parts of documents and communications material.
Internal Links
Process
Determine Purpose and Audience
All technical communication is done with a particular end in mind. The purpose is usually to facilitate the communication of ideas and concepts to the audience, but may sometimes be used to direct the audience in a particular course of action. The purpose may be something as simple as having the audience understand the details of some technological system, or to take a particular action using that system.For example, if the workers in a bank were not properly posting deposits to accounts, someone would write the procedure so these workers might have the correct procedure. Similarly, a sales manager might wonder which of two sites would be a more appropriate choice for a new store, so he would ask someone to study the market and write a report with the recommendations. The sales manager would distribute the report to all parties involved in making that decision.In each of these instances, the person who is writing is transferring knowledge from the person who knows to the person who needs to know. This is the basic definition of technical communication
The identification of the audience will affect many aspects of communication, from word selection and graphics usage to style and organization. A non-technical audience will not understand, or worse yet, even read a document that is heavy with jargon, while a technical audience may crave extra detail because it is critical for their work. Busy audiences will not have time to read an entire document, so content must be organized for ease of searching, for example by the frequent inclusion of headers, white space and other cues that guide attention. Other requirements will vary on the needs of the particular audience.
Identification of multiple audiences indicates that multiple concepts may need to be communicated, and planning for this situation by first identifying the following for each audience:
- Purpose
- Needed information
- Educational Background
With this information, important needs can be satisfied in a way that caters to all. If this is not possible, audiences may be prioritized by importance, and serving important audiences first.
Collect Information
The next step is to collect information needed for accomplishing the stated purpose. Information may be collected via primary research, where the technical communicator conducts research first-hand, and secondary research, where work published by another person is used as an information source. The technical communicator must acknowledge all sources used to produce his or her work. To ensure that this is done, the technical communicator should distinguish quotations, paraphrases, and summaries when taking notes.
Organize and Outline Information
Before writing the initial draft, it is important to organize all the ideas in a way that will make the document flow nicely. A good way of doing this is to write all random thoughts down on a paper, and then circle all main sections, connect the main sections to supporting ideas with lines, and delete all irrelevant material.
Once each idea is organized, the writer can then organize the document as a whole. This can be accomplished in various ways:
- Chronological: This is used for documents that involve a linear process, such as a step-by-step guide describing how to accomplish something.
- Parts of an object: Used for documents which describe the parts of an object, such as a graphic showing the parts of a computer.
- Simple to Complex (or vice versa): Starts with the easy to understand ideas, and gradually goes more in-depth with complex ideas.
- Specific to General: Starts with many ideas, and then organizes the ideas into sub-categories.
- General to Specific: Starts with a few categories of ideas, and then goes more in-depth.
Once the whole document is organized, it's a good idea to create a final outline, which will show all the ideas in an easy to understand document. Creating an outline makes the entire writing process much easier and will save the author time.
Write the First Draft
After the outline is completed, the next step is to write the first draft. The goal is to write down ideas from the outline as quickly as possible. Setting aside blocks of one hour or more, in a place free of distractions, will help the writer maintain a flow. Also, the writer should wait until the draft is complete to do any revising; stopping to revise at this stage will break the writer's flow. The writer should start with the section that is easiest for them, and write the summary only after the body is drafted.
Revise and Edit
Once the initial draft is laid out, editing and revising must be done to fine tune the draft into a final copy. Four tasks transform the early draft into its final form:
Adjust and Reorganize Content
During this step, go back to the draft to ...
- Focus or elaborate on certain topics which deserve more attention
- Shorten other sections
- Shift around certain paragraphs, sentences, or entire topics
Edit for Style
Style refers to changes that make the writing more interesting, appealing, or more readable. Some changes are made by choice, not for correctness, and may include doing the following:
- Shorten paragraphs
- Rearrange paragraphs
- Change passive-voice sentences to an active voice
- Shorten sentences
- Define terminology
- Add headings, lists, and graphics
Edit for Grammar
At this point, start looking through the document for grammatical errors, such as comma usage and common word mixups. To get the most out of this step, pay special attention to mistakes which you have repeatedly made in your previous writing.
Questions and Answers
- How do I get into technical writing?
- Should technical writers be certified?
- Where can I get a degree in technical writing?
