Technical Writing Part Four: 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, Scribus

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: OpenOffice Writer, WordPerfect, Microsoft Works, AppleWorks, 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, Inkscape / Sodipodi
Other paint Programs: Jasc PaintShop Pro, MacroMedia Fireworks, GIMP

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 FrameMaker or Visio. Acrobat reformats files from other programs into PDF files. These files can be read like an online book. PDF files can be created using a number of different small programs, but most of those programs are limited in their abilities. Acrobat gives the technical writer a more expansive tool that can control a number of different document features.

PDF Reading Program: Adobe Acrobat Viewer (free)
Other PDF conversion programs: PdfEdit995, SolidConverter, Preview

Technical Writing Part Three: 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.

Technical Writing Part Two: What a Technical Writer Writes

The range of writing a technical writer performs varies widely. Much is dependent on the technical specialty of the writer and of the needs of the company. You may find yourself a part of one large project, or overseeing dozens of smaller projects. You might write 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.

Technical Writing Part One: Process Overview

Technical writing as a field covers many different areas. Many people, when they think of technical writers, think of user manuals for their favorite (or least favorite) software application. That is certainly one job a technical writer might have, but it is far from the only job. Some technical writers spend much more time working of reference materials, which can take the form of long books filled with technical information but very little in the way of instructions. Some technical writers spend their time creating online help files for people with specific problems that occur within an application. Other technical writers rarely work on new information at all; they spend their time updating old manuals or datasheets. Many technical writers work on a large team focused on creating a single document or set of documents. Other technical writers find themselves in charge of every single technical document an organization produces. A technical writer may create a single sheet of information or a thousand page book. The occupation is very diverse.

A technical writer’s primary task is to present specialized information to an audience. There are several important steps to the process, but 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
2. Determine the needs of the audience
3. Determine the documents required to meet the needs of the audience
4. Design the documents and present the information
5. Test to determine if the documentation meets the needs of the audience
6. Edit the documentation
7. Publish the documentation
8. Revise the information as necessary throughout the lifecycle of the document

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

Out With A Cold

I have been sidelined with a bad cold, which is why I haven’t been posting for these past few days. Traffic is pretty low this week due to all the holidays, but I still hate to leave people without something to read, so I am going to rerun my introduction to technical writing. Technical writing has been putting food on my table since 1995, so if you want to know how to make a living as a writer, you might want to read the series.

Next Page »