Authoring Software

Software technical writers use

If you’ve done any research on the various types of authoring software out there, I’m sure it has sent your head into a tailspin. What do technical writers really use? Which one is the best? Which one will suit your needs? What do employers prefer?

One of the most important factors to keep in mind is whether your documentation will be in print only, webhelp only or both. I don’t advocate one software over the other but, I’ll discuss just a few of them along with the pros and cons that I have personally found with those listed. These are also authoring softwares that I have used myself and by no means include all that are available out there. I’d highly recommend for you to conduct some research of your own to find out which ones might work best for you, along with the industry you choose to enter.

I have listed the current cost of each of the softwares I discuss. The costs are really most applicable to the freelance tech writer, so they may appropriately be factored into your start-up budget. Cost probably won’t be an issue should you choose to work for an employer, as they generally provide the needed software.

Let’s delve into my preferred print authoring softwares first:

§   Adobe FrameMaker (www.adobe.com/) 

§   Microsoft Word (www.microsoftstore.com)

Adobe FrameMaker is a great “What You See Is What You Get (WYSIWYG)” software, meaning that it will appear in print, the same way it appears on the screen. Perfect for print manuals, it simply requires the setup of a master page and your paragraph tags. Set those two up and you can basically sit down and start writing. The only disadvantage that I personally noticed, was that your master page creation can take a bit of time if you have no training in master page creation however; Adobe luckily offers some great training resources. You can also find some great forums and blogs that discuss Frame. Most of these resources (at least the ones I found) were free and extremely helpful. Frame is also great for importing images. You can anchor them to your paragraphs to prevent them from moving around or skewing when you place your documents into Portable Document Format (PDF).

Just as a quick side note…you will more than likely create a PDF of all of your Frame documents. The reasons for this will be that most engineers and SMEs will not have Frame installed on their machines. As a result, they will need to view a PDF of your document in order to review it. Your guides may also be available to your end-users for download. This is where the PDF document comes in very handy.

Back to Frame…it is a great authoring tool however, depending on your budget, the price can be pretty steep. As of the day I write this booklet, the cost for FrameMaker 11 (the newest version) is $999.00. As far as learning the software before you actually use it, Adobe generously offers free, 30 day trials. This is a great opportunity to familiarize yourself with the software and to get a feel for whether or not it will suit your needs before actually making a purchase.

Frame can also be used to create online documentation, so if you feel you may eventually be going that route, you may want to keep this in consideration.

Microsoft Word is the choice for some employers and freelancers in creating print documentation. It is very similar to Frame in that you can set up your paragraph tags, and then sit down to write. It’s not necessary that you do this however. It does come with a standard set, but I would highly recommend creating your own for customization sake. It’s not absolutely necessary to customer however and considering that most people have a basic knowledge of Word, it’s easy to sit down and start typing away.

Also like Frame, Word docs can easily be printed into PDF and in fact, is highly recommended. Due to the popularity of Word, you’ll find that most people have it installed on their machines. As a result, others can make unwanted changes within your documentation. This of course, is something that most tech writers want to avoid for obvious reasons.

As of the day I write this booklet, the cost of Word is very affordable for most writers. Version 10 (the newest version as of today), will cost you $139.00. I have found issues in using Word for technical documentation however, so I’ll share them with you and let you be your own judge. I do not find the product to be as “user-friendly” as Frame. For instance, Word documents can appear differently to people who have different versions installed. You may lose some of your formatting, styles, etc. I haven’t had this problem when using Frame. It appears the same regardless of the version being used. Some of the features will be different of course, but not the appearance.

Word is not typically used (as far as I know) to create any form of online documentation. If you ever plan on going that route, you may want to steer away from using Word altogether.

All in all though, Word is affordable, most people already have a basic understanding of it, find it relatively easy to use and require little to no training to create usable technical documents.

As I mentioned earlier, these two softwares are by no means all that you will find on the market. Research, research, research!

I’ll now give a brief discussion of a couple of softwares that are good for creating webhelp documentation:

§   Madcap Flare (www.madcapsoftware.com/)

§   Oxygen XML Author (www.oxygenxml.com/)

Let me give a quick note of what I mean when I use the word, “webhelp.” According to DMN Communications, “WebHelp is a method for delivering online help or documentation in a Web browser. WebHelp is simply a set of HTML and Java files.”

Madcap Flare is an excellent tool for creating just about any type of documentation, and is awesome for webhelp. It even allows the user to import documents created in other authoring softwares. Flare does have its drawback though. It requires the user to set up styles and such using a cascading style sheet (CSS). This is actually what customizes your Flare output to match a specific style. If you are freelance, your clients will probably request their own unique styles for their documentation. Setting up this output can be a difficult task unless you have CSS knowledge. This will require you to learn some CSS, or to more than likely work with a consultant for assistance in setting yours up. As far as creating your actual documentation in Flare however, you will be able to find a lot of useful help on various blogs, forums and discussion boards by other Flare users, not to mention the fact that Madcap seems to offer great technical support. They also offer training courses for a fee, but having been through one of these myself, I feel it was well worth it and extremely helpful. Do keep in mind that Flare is not a WYSIWYG tool. In other words, your documentation will appear different once it’s been compiled and implemented into the software, than what it appears onscreen as you are authoring.

Madcap Flare, although appearing steeply priced at $999.00, is a great purchase that is well worth the money, depending on your needs.

Oxygen XML Author states on their website that the product, “enhances the authors productivity by providing a clean and easy to use interface specially suited for content authors.”

I must be honest when I tell you that I have only dabbled a small bit in Oxygen however, fellow tech writers assure me it is a great tool. Like Flare it is not a WYSIWYG but, it provides easy document sharing between authors (using its Subversion Client) and it supports the editing of Microsoft Office and Open Document Format files. Oxygen XML Author will cost you about $349.00 but like the others, it does offer a free, 30 day trial. You will find that Oxygen users are very loyal to their product and they will tell you that you can find great support from the company, and in forums, boards and blogs should you choose to purchase this one.

The largest disadvantage I saw with this software is that it’s not easy to use unless you have had some kind of formal training. I would highly recommend you research the various training options before you make your purchase.

Comments