There are different breeds of technical writers. Some are masters of Microsoft Word, having learned every hidden feature and function (don't laugh, it's actually a very powerful application, but most of it's hidden so as not to scare your grandma). Others shell out a lot of cash for fancy authoring tools like Flare, RoboHelp or Author-It that do everything but walk your dog, and others settle midway for a not-really-best-of-either-but-at-least-it-wasn't-pricey* option, such as pairing Adobe InDesign with a very organised set of text files. Where I currently work, I have the advantage of my employer's Author-It license, but as a contractor I've been considering what I'll do in future.

One big beast: word processors

The word processor is still the chief tool of most technical writers, sadly enough. Which is fair enough, in some ways - Microsoft Office has long been something the everyday person assumes they'll always need, and feels comfortable using (though it would be nice if Microsoft stopped trying to hamstring inter-operability). It's a very logical, procedural process - you start at page one, and your write your document through to page X. Proofread, format, index, and we're done.

Except there's no such thing as 'single sourcing' in Microsoft Word - or any word processor, for that matter. If a particular feature set requires the same three pages of instructions, you're going to be copying those three pages a whole bunch of times - and if something in those instructions changes, you have to go and change each and every little bit, and then check the entire document to make sure you didn't miss any that were in some other section for some reason.

You can't break a document into chapters without destroying your contents and indices, so your project is in one giant unwieldy file that can too-easily become corrupted. Nobody else can work on the project at the same time without a lot of shenanigans with multiple versions and copy-cut-paste, and trust me, something will get lost or corrupted on that path.

Word is fine for school assignments, writing resumes, and really tiny documents done on-the-fly, but when compared to some of the custom designed applications, it's not a professional's tool. A disclaimer, though - I am, by no means, an expert in Word. What I've just said might well be completely untrue for someone who is skilled in the full functionality of the program - maybe you can hack your way into getting single-sourcing, topic-based authoring, but in my opinion, you're trying to use a hammer for a chisel, and that's a long learning curve to sit for yourself when there are other options out there.

Half-and-half: desktop publishing software

One of my main complaints with Word was the lack of single-sourcing - the ability to write a piece of content once, and then re-using that exact piece multiple times. If I change the original, all the others reflect that change. Single-sourcing is one of the most important concepts in technical writing.

You can - sort of - address this issue by combining a desktop publishing application like Quark or InDesign with your word processor. Essentially, you write the content in hundreds of extremely well-organised text or word files. Then, you use the desktop publishing program to lay out the document, placing and re-placing the content, and adding the styles, formatting and images.  If you need to change the content, you go back to the original text/word files and change it there. If multiple people need to work on a project, they can (as long as it doesn't use the same content). You can even break the project into separate chapters without destroying indices, so people can lay out different chapters at the same time.

Because a desktop publishing program is designed to create fabulous-looking books, you also get a lot more control over layout and presentation that you do in word - or in the professional authoring tools, for that matter. But to be honest, it's a level of control you don't really need. Nobody really cares how beautiful the help manual is; they care about it being easy to understand and use. And the temptation to make things pretty is likely to add a lot of hours to your project.

That's the main issue with the halfway solution - it doubles your time to write the content, and then decide how it will be organised and presented. You have to remember to change the original source, not allow quick edits in the publishing software. And you have to be fastidious with your organisation and naming schemes or you'll never be able to find anything. (Example: the project I'm currently working on is a medium-large application. It has well over twenty thousand topics, or "text files" in this instance. If you don't name things properly, and put them where they should go, you'll lose them.) So you gain some level of professional control, but you lose time.

The uber-geek: LaTeX

I debated including this one, as it's yet to really emerge from its geek shell - LaTeX is a "document preparation system". It's a little like Word cross-bred with XML. It has "styles" like Word, but they're defined as not-very-but-similar-to-XML comments that aren't displayed in the final document. You create your content, and then run it through the application and it generates a finished document.

LaTeX is a dream for single-sourcing - you can create a plethora of tiny documents and run them together in any order that you like. It easily supports diagrams, complex mathematical formulae and images (far, far better than Word does) and it stops you losing time mucking about with the formatting because it's not a WYSIWYG editor. It's entirely text-based, and the document presentation it produces is easily good enough for technical writing purposes.

However, once again you're faced with a fairly steep learning curve, especially if you're flying in without any experience with computer science, HTML or XML - doubly-so if you've come fresh from Word, King of WYSISYG. And that same organisation problem crops up again - you're still dealing with thousands of tiny, tiny TeX files sitting around in an organisational scheme you've devised. Unless you're the world's most methodical person in the world, you're going to either lose time dreaming up the perfect schema, or lose files within a less-ideal one.

Expensive, but efficient

The main problem with the previous options were:

• a lack of single sourcing, or
  • the work around for single-sourcing giving organisation nightmares,
• too much time lost in WYSIWYG editing instead of content-writing
• inability to have multiple people work on a project

Can we solve this with money? Oh hell yes, and then some. Technical writing tools are built on 'topic-based' content-creation, which means the document is broken down into thousands of self-contained topics which usually contain one concept, procedure, or application screen. Topics can be included in other topics, which builds single-sourcing right into the program, and into your process. No need to build-first, structure later.

It utilises styles akin to Word, but in a representational, rather than literal way. From this one application, you can publish Word documents, online help, CHM and java help files and a host of other things, each of which will look different. So there's no point to a 'real' WYSIWYG editor - wich version would it display? The software shows an approximation of the style: enough for you to see what you're doing, but not enough to get distracted with how it looks.

The application sits on top of a database, and has multiple, redundant searching and locating protocols in place, neatly solving your organisational dilemma. It only locks the files someone is actually working on - multiple people can easily work on the project, as long as they're not hoping to edit the same topic. And there's more. There's variables and dynamic structuring and a whole host of features that make techwriting so much more efficient.

But is it worth the money?

It's not as pricey as you'd think. The cost tends to scale with things like add-on packages, and how many people will be using the system. For a sole contractor with just the barebones application, you're looking at under AU$2000 for something like Author-It. Which admittedly is a lot more than Word, and certainly a lot more than LaTeX (which is free, by the way). But it gives you a hell of a lot more, and I think, before my contract runs out, that's definitely where I'll be heading.

*Well, it's not pricey if you buy it as a student.

• Add New
• Search
• RSS

Comments (0)

Write comment

Your Contact Details:

Name:

Email: do not notifynotify

Website:

Comment:

Title:

Message:

Security

Please input the anti-spam code that you can read in the image.

Powered by !JoomlaComment 4.0 beta2