Top
Browse > Home / Archive: December 2007

Technical Writing Part Four: Desktop Publishing Tools

December 31, 2007 by John Hewitt · 7 Comments 

Technical WritingThe 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

Filed Under: Technical Writing, Writing
Tagged:

Technical Writing Part Three: A Technical Writer’s Skill Set

December 30, 2007 by John Hewitt · 5 Comments 

Technical WritingBecoming 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.

Filed Under: Technical Writing, Writing
Tagged:

Technical Writing Part Two: What a Technical Writer Writes

December 29, 2007 by John Hewitt · 1 Comment 

Technical WritingThe 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.

Filed Under: Technical Writing, Writing
Tagged:

Technical Writing Part One: Process Overview

December 28, 2007 by John Hewitt · 3 Comments 

Technical WritingTechnical 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.

Filed Under: Writing, Writing Business
Tagged:

Some Recently Published Books of Poetry You Might Want to Read

December 22, 2007 by John Hewitt · 1 Comment 

30 Poems in 30 DaysFor my 30 Poems in 30 Days Project, I referenced quite a few poets. This is the source list I made up initially for the books I planned to promote during the project. It isn’t an exact match for the project because I went off on a few tangents as the 30 days moved along, but it is a good list of recently written books of poetry that you might want to check out.

  1. Portrait of the Artist As a White Pig: Poems by Jane Gentry
  2. Music for Landing Planes By: Poems by Eireann Lorsung
  3. Red Clay Suite (Crab Orchard Series in Poetry) by Honoree Fanonne Jeffers
  4. Blind Date With Cavafy by Steve Fellner
  5. The Curator of Silence (ERNEST SANDEEN PRIZE) by Jude Nutter
  6. Key Bridge by Ken Rumble
  7. Spring Poems Along the Rio Grande (New Directions Paperbook) by Jimmy Santiago Baca
  8. Painted Snowflakes: A Book of Poems by Heather Rae
  9. Galvanized by W. Joe Hoppe
  10. The Most Secret Window by Natalie Vanderbilt
  11. A Fiddle Pulled from the Throat of a Sparrow (New Issues Poetry & Prose) by Noah Eli Gordon
  12. The Resurrection Trade by Leslie Adrienne Miller
  13. Dummy Fire by Sarah Vap
  14. Roomanitarian by Henry Rollins
  15. Standing In Line for the Beast (New Issues Poetry & Prose) by Jason Bredle
  16. Selfwolf (Phoenix Poets Series) by Mark Halliday
  17. The Body is No Machine (New Issues Poetry & Prose) by Jennifer Perrine
  18. What Feeds Us by Diane Lockward
  19. Raven Eye (Sun Tracks) by Margo Tamez
  20. The Anteroom of Paradise by Bruce Bond
  21. The Road Home by Lyman Grant
  22. Notes on the Possibilities and Attractions of Existence by Anselm Hollo
  23. Occupied by Carol Mirakove
  24. Five Fathers by Arnie Goldman
  25. The Happiness of this World by Karl Kirchwey
  26. The Elephant House by Claudia Carlson
  27. The Heart is a Quarter Pounder: Poems by Jeffrey Miller by Jeffrey Miller
  28. What Narcissism Means to Me: Poems by Tony Hoagland
  29. Wind in a Box (Poets, Penguin) by Terrance Hayes
  30. Meteoric Flowers (Wesleyan Poetry) by Elizabeth Willis
Filed Under: Poetry
Tagged: , , ,

A Totally Overboard Guide to Essay and Paper Writing on the Web

December 21, 2007 by John Hewitt · 3 Comments 

The Basics of Essay Writing

General

Outlines

Thesis Statements

Introduction

Body

Conclusions

Drafts

Essay Types

The Five Paragraph Essay

The Admissions/Application Essay

The Argumentative Essay

The Cause And Effect Essay

The Classification / Division Essay

The Comparison / Contrast Essay

The Critical Essay

The Definition Essay

The Exploratory/Descriptive Essay

The Expository Essay

The Informal Essay

The Literary Essay

The Narrative Essay

The Personal Essay

    The Persuasive Essay

    The Research Essay

    The Response Essay

    The Scholarship Essay

    Citation Guides

    MLA

    APA

    Chicago

    Turabian

    Other Style Guides

    Filed Under: Writing
    Tagged:

    Next Page »

    Bottom