Technical Writing

Posted by admin on June 7, 2007 under Technical Writer | Be the First to Comment

Technical writing as a field covers a variety of different skills and positions. Many people, when they think of technical writers, think of user guides and installation instructions. That is certainly one area a technical writer might work in, but it is far from the only area. Some technical writers spend much more time working with reference materials, which can take the form of long documents filled with technical information but with little in the way of instructional content. Some technical writers spend their time creating online help files for people who need help navigating a particular application. Other technical writers rarely work on new information at all; they spend their time updating old manuals, files or datasheets. Many technical writers work on a large team focused on creating a single document or platform of documents. Other technical writers find themselves in charge of every single technical document an organization releases. A technical writer may create a single sheet of information or a thousand page book. Their work may be concentrated in print or online. The occupation is very diverse.

A technical writer’s primary job goal is to present specialized information to an audience. There are several important steps to the process, however, an individual writer may not be a part of all of these steps. These are the steps required to create useful documentation:

1. Analyze the information or data
2. Determine the audience’s needs
3. Determine the documents required to meet the audience’s needs
4. Design the documents and present the information or instructions
5. Test the documentation to determine if it meets the needs of the audience
6. Edit the documentation
7. Publish the documentation
8. Revise the documentation as necessary throughout the lifecycle of the project

Often, a writer finds that they are working on only one or two segments within the documentation path. A writer may take a job in which they work primarily as a document editor, or they find work revising existing documentation. This can lead to different job titles. A person may spend the majority of their time performing audience analysis and acquire a title as a usability designer or an information architect. The person who primarily edits/revises documents might be called a documentation editor or technical editor. A skilled technical writer, however, must be prepared to execute the entire documentation process.

What a Technical Writer Writes

The range of writing a technical writer performs covers a wide range of projects. You may find yourself a part of one large project, or overseeing dozens of smaller projects. You might write wen help, manuals, articles, proposals, white papers, product descriptions or any of a hundred other types of documents. Common documents types include:

Instructional Guides

Instructional guides come in a wide variety of types such as: user manuals, user guides, handbooks, how-to guides, set-up guides and quick start guides. Instructional manuals can be as short as a single page or longer than a thousand pages. The purpose of an instructional guide is to teach a user how to perform a task or a set of tasks. A single project can generate several instructional manuals. For example, a new relational database program may come with quick-start sheet, a user’s manual, an administrator’s guide and a programmer’s handbook. All of these are very different documents, but they all come under the heading of instructional guide.

Informational Material

Informational material also covers a wide number of documents such as reference books, datasheets, application notes, FAQs (Frequently asked questions), white papers and process analysis. The purpose of these documents is to provide information more than instruction. The previously mentioned relational database program might include a reference book that lists the database commands and what they are used for. It may also include a datasheet that lists the application size, available platforms, limitations and known conflicts/issues.

Business Communications

Businesses communications are not necessarily technical communications, but a large segment of technical writing is deeply involved with business communications. These communications take the form of proposals, service level agreements (SLAs) and standard operating procedures (SOPs). For example, a business may want to use an outside vendor to provide call center services for their new product. The first document they would create is a request for proposals (RFP) that describes what services they need and invites other companies (vendors) to submit a proposal. Prospective vendors will then submit proposals. These proposals are both a sales tool and a technical document that provides details about how the vendor intends to provide the service. Once a vendor has been chosen, they must contractually agree to the provision and division of services. This agreement is an SLA. It describes what each company is responsible for providing and maintaining.

SOPs are much like instructional guides because they define how to perform a task, but in business they are generally more restrictive. That is because an SOP may be binding. In other words, if an employee fails to follow an SOP they may be fired or reprimanded. If a company fails to follow an SOP they may lose a contract and be liable for damages.

A Technical Writer’s Skill Set

Becoming a technical writer involves the mastery of a set of skills. A carpenter must master hammering, drilling and sawing. A technical writer must master writing, technology, tools and other skills.

Writing Skills

The first skill a technical writer should have, of course, is writing. You should be able to write in a clear, concise manner. Technical writing is not poetry or prose. Depending on where you work, you may or may not be able to add some stylistic flair. Either way, your job is to clearly tell your audience exactly what they need to know, and everything they need to know.

Technical Skills

The second skill you should have is knowledge of a technical subject. My emphasis has always been in the field of computers, which is probably the largest segment of the technical writing market. Your knowledge can be in many other areas, however, such as science, medicine, engineering, mechanics, or law.

Tools Skills

No matter what your area of knowledge, you will need tool/computer skills, especially desktop publishing skills. At minimum, you should know the Microsoft Office suite of applications, especially Microsoft Word. Beyond Office, there is Adobe FrameMaker, which is used in many technical-writing environments. Other publishing packages such as PageMaker, Quark Express, and Interleaf can also be useful. In addition, online documentation tools such as RoboHelp, Doc-to-Help and Lotus Notes are great applications to have on your resume, as are HTML and other Internet skills.

Other Skills

You should try to develop interviewing skills, because you will probably find yourself interviewing technical people to get the information you need for your documents. Often, they will have no idea how to tell you what you need to know, so it is up to you to figure out how to draw the information out of them.

Visual design is another key tool for document development. Technical documents are not composed of just text; they contain graphics such as tables, icons, visual aids, schematics, graphs and charts. Knowing how to work with these visual tools is a key to creating a quality user experience.

Usability and testing skills are also valuable to a technical writer. It is important to learn how to test documentation to make it better. Learning the basics of usability testing will aid you when it comes time to test your own work and to incorporate the results of those tests.

Desktop Publishing Tools

The production of printed documents using a computer is called desktop publishing. At its most basic, desktop publishing requires a computer, a printer, and some sort of text or graphics program. While you can achieve desktop publishing using something as simple as a word processor, the applications used by technical writers are often more sophisticated and expensive than those used for common office applications. Because technical documents are often longer and more graphically complex than general business or personal documents, they require programs that are designed to handle these tasks. When technical writers do use common office applications, they are frequently required to use features that most users never need. For example, Microsoft Word has index and table of contents tools. Those tools aren’t very flexible and can be difficult to use, but if Microsoft Word is the only desktop publishing application at your disposal you may find yourself putting those tools to use.

Adobe FrameMaker

FrameMaker is a desktop publishing program developed specifically for the writing of long, technical documents. FrameMaker has three main sets of features that make it a great tool for technical writers.

1. FrameMaker’s book features help you to work with long documents by dividing them into chapters within a single book. This allows for the creation of cross-references, indexes and a table of contents. In addition, you can assign styles and variables for the entire book.
2. FrameMaker’s template features provide for the creation of multiple templates that can be applied to different pages in the same document through the use of master pages and reference pages. For example, you can apply different page templates for your cover, front matter, body pages, chapter pages, glossary, index and back matter.
3. FrameMaker’s graphics handling allows you to attach graphics to individual paragraphs. This makes it easier to add new text without worrying about how it will flow around the graphics.

While FrameMaker is a powerful, useful program for technical writers, it is not without drawbacks. FrameMaker is harder to use than a word processor and requires a different, more systematic approach to document creation. Learning to use all of the features takes time and commitment. It is possible to create a memo or a quick note with FrameMaker, but that is not what it is built for.

Other page layout applications: Adobe PageMaker, Quark Express

Microsoft Word / Office

Microsoft Word is not a bad tool for technical writing, but it isn’t a good tool either. The primary appeal of Microsoft Word is its universality. Almost every office computer has this program. This means that you can write a document and send it to anyone else involved in the project and they can work directly with the document. Of course, many writers would prefer than no one else touch their document, but that is a different issue. Microsoft Word can also come in handy when you need to create small documents quickly, especially those that will be importing information directly from other Microsoft Office programs such as Excel, PowerPoint and Access.

The limitations of Microsoft Word are generally felt when you start to create longer documents or work with graphics. These tasks are not the application’s strengths and when documents get too complicated Microsoft Word tends to slow down, crash or “lose” information.

Technical writers are frequently called upon to use the other applications in the Microsoft Office suite. Projects are often tracked using Excel or Access, and technical writers are sometimes required to create PowerPoint presentations.

Other word processing applications: WordPerfect, Microsoft Works, Claris Works, StarOffice

Adobe Photoshop / Adobe Illustrator

Photoshop and Illustrator are both image creation and manipulation programs, but with different emphasis. Photoshop is primarily what is called a paint program. Users can color or recolor (paint) the individual pixels of an image. Illustrator is a draw program. It is oriented toward creating images using lines. In other words, if you specify that a line moves from point A to point B, Illustrator will create the line based on those points, and the user can change the line by simply changing one or both of the points. When you use a paint program, every pixel has the same importance as every other pixel.

There are advantages and drawbacks to both systems of image creation and manipulation, and both programs include some of the other’s abilities with respect to creating lines or working with pixels. The main difference between the two programs is emphasis. If you primarily need to draw, you use Illustrator. If you primarily need to work with images, especially imported images, then Photoshop is the more appropriate tool.

Other draw programs: Corel Draw, Macromedia Freehand, AutoCAD, EasyCAD
Other paint Programs: Jasc PaintShop Pro, MacroMedia Fireworks

Microsoft Visio

Visio has some of the features of draw and paint programs, but it has a much different emphasis. Visio is used to quickly create flowcharts, graphs, charts, schematics and other technical or process-based images. Visio accomplishes this by providing the user with icons, chart and line tools that can quickly be placed and connected on the page. Each icon is also set to allow the input of short descriptive text. The learning curve for this application is twofold. Not only does the user need to learn how to use the tools of the program, but they also need a firm grasp of the theories behind the creation of these images and how they are used to present information.

Other process design programs: SmartDraw, iProcess, OmniGraffle

Adobe Acrobat

Adobe Acrobat is a program that makes it possible to share documents across multiple platforms. This makes it easy to give other people a polished electronic or print copy of a document in a format that does not require that they have your base program. In other words, you can turn a FrameMaker or Visio (or other) file into a PDF file that can be viewed by people who do not own or use FrameMak