Sharp Words

I’ve mentioned before that to do their job, a technical writer these days needs to know their way around quite a few software tools. Here’s a round-up of some of the more common ones used for authoring and publishing documents and online help.

Disclaimer: there are plenty of other software applications out there (including on other operating systems – these are all Windows-based), and a whole load of ancillary tools such as ones used for graphics. These are just the ones I’m most familiar with.

Microsoft Word
The ubiquitous word-processor. Frankly, if there’s another (better) tool you can use to create documents with, use it. If you do have to use Word, then make sure you get some training or read a good manual (in other words, not a Microsoft one) and learn how to do things like create templates and maintain styles, in order to get the best out of it.
On the plus side, it’s used by most people so it’s easy to share documents around. And if you do just want to write something simple and short (Word doesn’t do long documents very well), then it can definitely be easier sometimes to just put it together in Word. And some other software tools – such as RoboHelp and Author-IT – use Word as an output format, again because it’s used by so many people.

Adobe FrameMaker
An authoring and publishing tool (part of the Adobe Technical Communications suite). I admit to not knowing an awful lot about FrameMaker except that judging by the summaries I used to do of the ISTC mailing list, it has a lot less bugs than Word! Its main selling points are that it provides structured authoring, and that it can publish to a variety of formats. It supports XML, which is increasingly an important standard in technical documentation.

Adobe Acrobat
Used for creating and manipulating PDF (portable document format) documents which can be published and read just about anywhere in an application that can handle them. A lot of companies publish their manuals in PDF format to be distributed over the net or on CD.

Adobe RoboHelp
Another Adobe product (although it’s gone through several ‘owners’ since I’ve been using it), RoboHelp is used for creating WinHelp, HTML Help and Webhelp formats, amongst other things. It has its own source control, and supports XML.
It can be used to single-source documents (in other words, publish in ‘print’ format (usually Word) as well as help files or web pages), but it’s not really that good at it – I’ve only ever used it for creating help files. It’s got a decent WYSIWYG editor, but since all its files are stored as HTML pages, it’s possible (and sometimes necessary) to edit the HTML code directly.

MadCap Flare
This is another help creation tool, and came into being when RoboHelp was bought by Adobe (who, if I remember right, were initially going to phase it out). It seems to be doing reasonably well as a competitor; again, it offers single-sourcing, source control and XML support.

Author-IT
The tool I currently use, and one I’ve grown quite fond of (if that doesn’t sound like a daft thing to say about a bit of software). It’s another authoring and publishing tool, which lets me use the same source material to create both documents and online help (which saves time, of course). It’s also very good with content re-use, which means that I can change a sentence in one place and have the change reflected in every guide where that sentence appears.
Like RoboHelp and MadCap Flare, it has its own source control and of course, supports XML.
It has its downsides: one is a reliance on Word, and another would be the limits of the way it handles text styles. But on the whole, it’s working well for me.

Anyone got any other favourite authoring and publishing tools, or can share something about non-Windows ones?

[Note: I did have a post up called 'A missing post' because I thought I'd published and lost this one. But it turned up, with a published date of May 27th - so I've tweaked the date and taken down the other post. Phew.]

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts