documentation writing tools

Factual Questions
1

Have a project underway that’ll require docs. I’ve been through several companies where we’ve used Word (which was fine until the size of the doc grew, and then it imploded.), Pagemaker, and FrameMaker, and I’m pretty familiar with the capabilities of each. Ultimately, we’ve ended up with FrameMaker each time.

So, my first thought is just to go to FrameMaker, which has been successful in the past.

I’ve been playing with a couple of new-fangled ideas:
One is to do the docs on our corporate wiki, which will allow people throughout the company to make appropriate changes. But I don’t have this fully thought through yet. The main problem area’s are that the input isn’t WYSIWYG and the output to PDF isn’t there currently.

Another idea is to do pieces of the docs in xml, and have code that builds the docs from that. The reason for this is that xml is used extensively through our product, and in addition to the info going to the docs, including it in the product xml code allows us to use the help text inside the product in various ways. We already have this in place in one part of the product/docs, and I’m very pleased with the results, so I’m thinking about extending it as much as possible. Also, we don’t have a means to output this to PDF yet.

Requirements:
The manuals will be hefty, perhaps 300 pages each.
Output in PDF and HTML.
NOTHING THAT WILL REQUIRE A MAC (sorry to offend any fine doc writers here who prefer that platform, and I’m sure there are many, but there will be no macs here).

Any thoughts/recommendations on products or techniques will be appreciated.

Thanks.

2

One big advantage of having the content in a wiki is that it’s in a database where you can manipulate it. The tools to dump wiki to PDF may not be there, but it seems like if you had your text in a well-designed database structure where topics were not only defined but ordered in some hierarchy, it would be a fairly simple project to write a database dump that put it in a variety of formats. This would allow you to dump a snapshot of the current docs in XML, PDF or a variety of other formats pretty easily.

Going straight from DB to PDF might be harder than necessary because of the way PDF headers have to be structured, but writing formatted text into Word is pretty simple, so you could have a script that read your DB and wrote a properly-formated Word (or probably Framemaker, though I’ve never done that) file just like the wiki is reading it to render HTML. Then a print-to-PDF gets you the output you want. The script to read the data and create the formatted document implicitly includes a style definition, so you can easily change the format of the entire document just by modifying the script and running a new copy.

This might not be the easiest way to get to a final PDF, but choosing to maintain your document in a database structure gives you a lot of flexibility to choose different output formats later. Of course, the same is true if you use an XML source document, but if it were me, I’d choose to maintain the doc in a db structure and dump XML for portability as needed.

3

At work we use a package called Doors, but 300 pages would be classed as medium-sized and we have a lot of people.

4

I recently coverted one of the manuals I maintain from Word to DocBook (www.docbook.org). DocBook is an XML schema that can be converted using XML stylesheets to a variety of output formats including HTML and PDF. I needed to get away from Word because it was a hassle to maintain consistent formatting in a 700 page document split into multiple files.

Once the text has been marked up, the stylesheets handle a lot of the details like creating table of contents, lists of figures and tables, cross-linking, etc. All of the tools I used are open-source and built in Java. There are WYSIWYG XML editors available, but I didn’t use them, so I can’t comment on that; I just used a text editor with XML syntax highlighting (BBEdit to be specific, but that’s a Mac product :)).

5

Thanks, micco, qts, and Sparklo.

micco, I completely agree about having it in a database. That’s sort of what we currently are doing with a small piece of things, namely we have a list of mabye 250 items inside our product that each requre a few paragraphs of description each. Rather than write them into a manual directly, we plugged the descriptions into an xml file that ties into other aspects of these items. So not only can we read the xml file quickly and format it as we like for docs, we also can provide it as context-sensative descriptions inside the product. It’s very cool, and I want us to do more of this.

Sparklo, I’ve been looking into DocBook recently. Can you tell me what tools you use? Any things to watch out for? Any techniques I should be aware of?

Thanks.

6

I’m one of five tech writers at a small-ish software and services company. I’ve been in this field for six years, and have only ever used Word or FrameMaker to create and maintain documents; I understand the idea of DTDs (from seminars I’ve attended), but I don’t know enough to understand how they compare to an application like Word or Frame.

If my biggest doc is 250 pages and I always output as PDF, what is the advantage to maintaining a document as XML or in a database? Does it depend on the scope of the document, how many people will be contributing to it, etc?

7

Sorry for the delay in my response. Life moves fast around here…

For my DocBook work, I use Saxon 6.5.3 (http://saxon.sourceforge.net/) as the XSL processor. Saxon is written in Java and can directly create HTML output using the DocBook stylesheets (http://docbook.sourceforge.net/projects/xsl/). It can also create FO output, which is then turned into a PDF by a separate processor.

For the FO-to-PDF conversion, I started out using FOP 0.20.5 (http://xml.apache.org/fop/). It’s free and open-source but has some fairly serious limitations; the worst for me was its inability to not break figure and table titles across pages. Recently, I switched to XEP 3.81 (http://www.renderx.com/). This is a commercial product; I’m at a university so I have the free academic version.

Misnomer, I switched to DocBook since I was facing reformatting a set of large Word documents and preferred a non-proprietary option. I also wasn’t very happy with either the PDF or HTML output I got from Word. For people who are used to doing page-layout type editing, DocBook may not work for you since you don’t really see the format until after it’s rendered.

8

I’m a tech writer for a large software company that sells database software, applications, and tools. I work on docs for Java development tools.

I am an intermediate-level FM user: I know how to design unstructured templates for all the features that FM offers except equations; I know the principles of structured documents though I’ve never designed a structured template, and I know how to print FM docs to PDF and how to convert them to HTML.

I also use Dreamweaver MX 2004 to write online help (with our company’s own Java-and-web-based help system), and I write doc plans in our project’s Wiki.

You should be aware that I am not yet a big fan of single-sourcing. In doing any sort of documentation, I always focus on customer expectations and use cases:

[ul]
[li]If your customer is technically savvy, has constant access to online tools, is used to reading documentation online, and understands PDF/hyperlinks/wikis, then emerging technologies are a fit.[/li][li]On the other hand, if your customer always uses printed manuals, they may want printed manuals (at least initially) until they get used to online docs.[/li][li]Is this reference material? Reference material is a perfect fit for online docs. You can search for exactly what you need, and ignore the rest. But, you can do online docs from Framemaker.[/li][li]Is it procedural information (instructions). Short procedures are good for online, longer ones aren’t.[/li][li]Is it guidelines/architectural reviews/conceptual information. Online is not so good for this. Customers want something they can easily read through in large chunks, like a book. [/li][li]Is the documentation for software? Online documentation for hardware is very frustrating, especially when you’re trying to diagnose a problem with the hardware that prevents you from reading the online documentation about that hardware! I just got stuck trying to read the documentation for my fancy new Logitech Bluetooth keyboard/mouse combo. All documentation online. Every tried to navigate through Windows XP without a mouse!?[/li][li]Online documentation has to be organized differently than traditional book documentation. Unless you work hard to get the docs organized, your online docs will be hard to navigate. It can take 1-2 weeks to come up with an effective table of contents (TOC) for a large online doc set.[/li][/ul]

I use structured FM7 to write installation guides, guidelines books (how to use an API), release notes, and similar reference and pre-installation procedural guides. I have found it very easy to print to PDF from FM. Don’t save as PDF, print to Postscript using a Distiller driver, then convert to PDF. Works well.

Webworks Publisher can convert structured FM to HTML, or you can output structured FM to XML and then convert. If you do the latter, you have to develop your own read/write rules for FM. Adobe documents this.

Unless your documentation is only going to appear as part of online help for a software product, I strongly suggest you write it as a book. I have used our company’s books put online as HTML, and it works. I’ve never seen online help converted to book format.

Docbook is a good place to start for structured documents.

Last note:
I went from basically being a software developer to being a tech writer. My experience is that I was not an effective tech writer when I started. I took training classes to learn what I was supposed to do, and now I can do a reasonable job. Please, anyone out there, if you want a good manual/online help system, hire someone who has experience doing it effectively!

Despite all appearances to the contrary, this is not a resume (I’m very happy where I am) and not a plug for tech writers. Instead, it’s a plea from a long-time computer professional. I’ve discovered that bad manuals are a result of people not knowing some simple rules for writing manuals. Believe me, you are not a tech writer just because you know technology and someone has told you you write well!

Joe