how to make online docs efficiently?

November 2, 2005 4:40 PM

How best to manage software product documentation? Our product docs are written in Microsoft Word and printed or shipped as PDF files. The online help is made by converting the Word files (in Robohelp) and adding lots of hyperlinks. This process has snags.

The problem is over how to manage document changes. At present the Word files are the base which is edited for product updates.

Using Robohelp it's trivially easy to convert the .doc files to online form, but that loses all the work which went into the hypertext links. On the other hand, adding the changes manually to the hypertext is also a lot of work, and error-prone.

Surely there's a better way?

posted by anadem to computers & internet (10 comments total)

So the hyperlinks aren't in the word file and are added at a later stage?

If you can include them in your source that'd make the most sense (you'll be maintaining a single source, which is generally a good goal in document management).

If this breaks the PDF, you could still do it but mark up areas of the MSWord file with inline styles and use a macro to strip them before making the PDF.

Or, if you're feeling adventurous, you could use my software called Docvert to make an XML publishing system from MSWord to HTML and XSL-FO, and generate PDFs with Apache FOP.
posted by holloway at 4:57 PM on November 2, 2005

Adobe FrameMaker might be worth a look.
posted by kindall at 6:27 PM on November 2, 2005

FrameMaker is definitely what you're looking for. Its born & bred to do this.
posted by devilsbrigade at 6:33 PM on November 2, 2005

As was Corel Ventura. And LaTeX. And Docutils. And so on and so forth.

For the life of me, I can never understand why any halfway competent technical writer would submit to MSWord. The only worse way to accomplish the task would involve x-acto knives and one's own bare forearm.
posted by five fresh fish at 7:59 PM on November 2, 2005

(worse, but not necessarily more painful)
posted by five fresh fish at 8:03 PM on November 2, 2005

Write the documentation in HTML and provide it in HTML. No conversion necessary.
posted by megatherium at 8:27 PM on November 2, 2005

I wouldn't say it's completely useless. MSWord is good for loosely-structured 1-200 page work when the author knows how to use word styles.

It may sound like a niche category, but it's not bad at filling it.
posted by holloway at 9:08 PM on November 2, 2005

Definitely framemaker (former documentation manager for large software company here). That's if you're wedded to providing the documentation in PDF. However an XML solution would probably be best for long-term use as you could then output to various formats cleanly.
posted by miss tea at 5:00 AM on November 3, 2005

Both Framemaker and Ventura support parsing of XML to automagically lay out the publication. Ventura also has one of the most kick-ass database parsing engines.
posted by five fresh fish at 9:36 AM on November 3, 2005

FrameMaker + WebWorks is a dream--once you get all your Word docs converted to Frame and a basic template set up in WebWorks, it's a very, very fast process. Cross-references in FrameMaker are automatically converted to hyperlinks in WebWorks (though doesn't RoboHelp do this as well?) and you can use conditional text to add any HTML-specific hyperlinks to the Frame source so that when you print to PDF, it doesn't appear, but does appear in the online help.

In one company I worked at, we went from 2 weeks for online help creation to 2 hours to create help for multiple product lines and deliverables. At my current company, I used WebWorks Automap and FrameScript (it has its quirks and issues, but is definitely a timesaver) to automate the entire help creation process so we run a script to generate both PDFs and online help--so all you really need to stress about, for the most part, is getting that stuff written!

There *is* a bit of a learning curve (though in my experience, tech writers of every skill level were able to pick it up) and a lot of initial work required to tweak your Frame styles, WebWorks styles, and templates on both sides if you want something truly custom (as well as learning how to write your conditionalized help content--if you do that--*while* writing your User Guide-intended content...which is kind of a trivial mind-shift)...But once the initial set-up's done, you'll find you are saving considerable time in help creation (not to mention all those pesky Word crashes!).

It also takes a lot less time than a hand-built XML solution--which is nifty (and free!), for sure, but when deadlines are tight, you don't really have that much time to futz around with XSL-FO to get it looking the way you want...not to mention the hoops you have to jump through to get tables of contents, indexes, and other nifty things you may want in your help file! :)
posted by jenh at 11:05 AM on November 3, 2005