Tools for the Technial Writer

Tools for the Technical Writer

What tools do you need to succeed as a technical writer? Often, you need to know whatever tools your company chooses to use. Browse the want ads for technical writers and make a note of what software tool familiarity they are calling for. The catch-22 is, the average writer (especially one who is looking for a job, may not be able to afford to buy several software tools just to learn how to use them. Your best bet, again, may be to familiarize yourself as much as possible with the free trial software you can download. If you have a basic familiarity with the tools in wide use, you can get up to speed once you get hired and learn what tool fits your new company's system. In any case, here's an overview of the tools that technical writers are using and some links to find out more about them.

Code

HTML, XML, Javascript
Do you need to know markup languages or code to be a technical writer? Not necessarily, but it doesn't hurt. Let's take a closer look at what all these initials stand for in case they're new to you, then we'll talk about which ones you should learn more about and why.

HTML and CSS

HTML, or Hypertext Markup Language, is the lingua franca of the Web. HTML is a coding system that tells a web browser how to organize content on a page. HTML is a cross platform language, since it is designed to work with any web browser and any operating system.

One way to get an idea of what HTML looks like is to view it running behind any web page. When you're surfing the Internet, you can view the source code behind any web page by clicking on the View drop down box on your browser, then selecting View Source or Page Source. If you select one of these, your browser will open a new window containing a bunch of text and symbols that will look something like this.

<html>

 <head>

 <title>Moore Harp Service</title>

 <meta name="generator" content="Yahoo! SiteBuilder/2.5/1.5.0_02">

 <meta name="author" content="Rory Moore">

 <meta name="keywords" content="harp, harp regulator, harp technician, harp service, 

harp repair, Rory Moore, harps">

 <!--$page margin 0, 0, 20, 0$-->

 <!--$fontFamily Arial$-->

 <!--$fontSize 14$-->

Want to learn more? Take an online course in Technical Writing.

 <style type="text/css"><!--

 BODY {font-family:"Arial"; font-size:14;margin:0px;padding:0px;}

 P {font-family:"Arial"; font-size:14;}

 FORM {margin:0;padding:0;}

 --></style>

 <!--$begin pageHtmlBefore$--><meta name="description" content="Harp Service 

website of Rory Moore, harp technician. View Rory's harp service calendar and request 

service in your area. You'll also find articles, videos, and answers to your harp care 

questions."><!--$end pageHtmlBefore$-->

 </head>

This section of code is from the head section of a web page, so none of it is actually 
visible when the page is displayed, but it nonetheless gives information about the page 
to the browser and to any web spiders that may come across it to index it for the search 
engines.

The CSS, or Cascading Style Sheets, is a companion to HTML and exists side by side with it. While HTML tells the browser how to structure the text on the page, CSS, tells it how the page should look. Information about page color, text font and color, text size, and other matters of appearance are written in CSS. Here is a snippet of CSS from the code example above.

BODY {font-family:"Arial"; font-size:14;margin:0px;padding:0px;}

 P {font-family:"Arial"; font-size:14;}

 FORM {margin:0;padding:0;}

XML

The XML is another markup language (Extensible Markup Language), but it is concerned not with how text is displayed but rather how information is organized. Content in XML is organized by the assignment of tags. Information coded with XML tags can be remixed and repurposed in a variety of formats. XML is the magic behind a number of the cool Web applications that we use everyday, including RSS.

XML is also behind many of the programs used by technical writers, as it is useful in reorganizing content to fit into a variety of deliverable formats. Many of the tools we will mention are XML based. DITA

DITA stands for Darwin Information Typing Architecture. It is not a language, but an architecture, as the name indicates. DITA is a set of rules for structuring XML in a way that maximizes its potential for reuse. While DITA has been around for years, it is only beginning to come into wide use, and there are a limited number of commercial software tools that use it. Many predict that it will become a standard architecture for managing technical content. It may provide a platform for the concept of single-sourcing, and then every technical writer's dream of writing content once and then publishing it to any format that is needed, will become a reality. XHTML

XHTML is a version of HTML which is compatible with XML. It is likely that sometime in the near future, XHTML will become the standard markup language for all Web content. It is not a drastically different language than HTML, but rather more of an evolutionary step on the same ladder.

Java

Unlike the markup languages mentioned above, Java is a programming language used for writing programs that run in a web browser. Whenever you click a play button or click on a drop-down menu on the Web, chances are it is Java running in the background. There are other programming languages that can do similar things, such as Ruby on Rails, an open source programming language for writing Web applications.

As a technical writer, do you need to know markup languages and code? Not necessarily. As we've said, most writers use GUI (graphical user interface) programs to create content, and these create the code automatically. On the other hand, there are some companies where technical writers work directly in native XML.

Since the GUI tools are highly priced, a low budget startup company, especially one on the cutting edge of technology, may require its users to work in native markup languages. Even if this is not the case, though, it is very useful to know what is going on with a web page when you look under the hood. It can often be useful to make small changes to web content at the source code level, instead of using whatever web design tool your company uses. As a result, a working knowledge of HTML and CSS, and an understanding of how XML works will serve any technical writer well.

The average technical writer will not be expected to program Java or other web application languages. Generally, companies that need programming will have specialists who can do it. But as a member of a team that is likely to be creating online content, the well rounded technical writer should have a good understanding of what Java and other Web scripts are and what they can do, especially if your company's product is web based, such as a Google or an E-Bay.

Tools

There is a variety of software tools designed for technical communication. Here are a few, along with links that will show you where to learn more.

Adobe Technical Communication Suite is a family of software products designed to help technical writers manage every phase of the technical communication process. Well known Adobe products like Photoshop and Acrobat combine with more specialized tools, such as RoboHelp, for creating online help files, Captivate, for screen capture and other training applications, and Framemaker, a tool for authoring all sorts of user documentation.

Doc-To-Help, from ComponentOne, is another all-in-one authoring tool, using an XML based format to help users convert content into a variety of deliverables. ComponentOne is partnered with Microsoft and offers a high degree of compatibility with Microsoft products.

Madcap Flare is another XML based help offering tool, part of a suite of web and print publishing solutions.

Camtasia Studio is a popular tool for capturing and distributing screencasts for training, documentation, and sales.