Writing Tools

One of my fellow technical writers asked me a question that should have been easy enough to answer:

“After spending the last year using FrameMaker 8, what would you want to use if you started at a new company that didn’t have any existing documentation? Would you want to go back to LaTeX or would you ask them to pay for you to get FrameMaker?”

I was first of all amused that she didn’t assume that I would go for RoboHelp, one of the other documentation programs we use. There was also the assumption that I wouldn’t want to try something I’ve never tried before.

Then I had a think about it.

• Am I a lone writer because they have very little documentation that needs to be created or am I the first of what will eventually be a team of many?
• Is the documentation going to be online help, CHM, PDF?
• How much money does the company have to spend on documentation, after paying me?
• Does the documentation need to be released as soon as possible or is the software in the early stages of development, giving me time to develop the doc set?

All of these thoughts come together to decide how I would approach new documentation.

I know there are other tools available that I wouldn’t use for customer-facing documents, such as wikis (because of how difficult it is to keep them structured and ensure that all your pages are up-to-date) and plain text files (acceptable for short READMEs, but messy for long documents). There are also long lists of tools that I’ve never used before so don’t know the value of, such as Flare, DITA, and Author-It.

My first technical writing job, I worked for a very small company. I wrote everything in LaTeX, due to the ability to make a nice template, the ease of adding content, and the openness of the software to edit it. Free software to create the doc, ability to output as PDF and HTML. Everyone’s happy, right? Except most people don’t want to have to edit LaTeX because it can sometimes be fiddly and software developers have better things to do than chase an orphaned sentence.

If I were to go back and do it again, knowing what I know now, I would probably do the documentation in Microsoft Word, but with a fixed template. The developers left updating the documentation in my absence would be happy, and marketing could more easily copy text from the documents. Even the cost of the Microsoft Word license is effectively zero since everyone had it anyway. And in the end, I never did need the HTML help.

If I worked for a very small company that needed primarily HTML help and the occasional PDF, I would probably use Adobe RoboHelp. Compared to other documentation software, the license is cheap, I already know how to use it, I can create templates for it, and (as long as I’m very strict about how a project is organised) it can produce good HTML help as well as PDFs.

I’ve mostly enjoyed FrameMaker 8, this last year. Our template is solid and we’ve got a strict style guide, so our documentation is consistent across writers and product suites. I mostly like the user interface and I know that more recent versions have fixed those few things that really rub me the wrong way. It even has the very useful features of conditional text and text insets. But, it’s expensive. It gets even more expensive if you want it to create HTML or CHM, since you need WebWorks ePublisher.

If the company were intent on expanding, both in terms of software suites and staff writers, I’d push for FrameMaker. At that point, they can probably afford the licenses for it, and it gives a much more structured doc set.

If the expanding company also had time to let me research and try different things first, I’d really want to give Structured FrameMaker a try. The idea of XML organisation in documentation makes me pleased as punch and, from what I’ve read about it, sounds like the sort of thing I’d really like to use.

This is one of the things I like about working with different people on different projects – I get to learn about all sorts of new tools. Maybe my next job will need me to learn DITA.