Manual Writing Tools?

Saulo Achkar writes "I've been recently assigned the task to rewrite the user's manual to a piece of relative complex software. Today, the existent manual used was developed with reStructuredText, a very nice piece of software; unfortunately, we're not able to create classes or templates for things like similar interfaces (that share the same functions), which means we need to write more code and that means more editing. XML formats aren't very friendly to code or edit in, either. What kind of techniques or tools are there to make writing manuals a bit friendlier and faster?"

Comments

How about Word?

[JeffHunt]

Or OpenOffice? Word processors are good at processing, uhm, words... you know.

LaTeX

[calumtdalek]

LaTeX is awesome for technical writing.

Re:A spelling checker, for one

[Anonymous Coward]

I am guessing that the guy who wrote the coherent lead probably did not write the illiterate headline.

Digital had a neat pattern

[Nefarious Wheel]

Digital Equipment Corp was known for their well laid out, informative and easy to use VAX/VMS manuals (cue old "three rooms of heaven" jokes). They were highly automated. They used Edit/TPU templates for coding that enforced carefully structured comments in program code, followed by a program that stripped the comments from programs written that way and structured them into a book, with appropriate fonts and styles. What followed was simply editing the output of that program and printing it, a much easier job than writing the entire document from scratch.

In the days before OO programming your quality of work was often measured by the quality of your code comments and intelligent use of white space. Readability was seen as one of the requirements for maintainability. Good data structures and clean algorithms followed from that.

Have you ever noticed that code flows better when you can describe what you're trying to do in English first? It's kind of like learning to communicate well with yourself. We used to start with the program comments, in English, then fill in the blanks with code. It worked.

Re:Use another person

[bwhaley]

Yes. Preferably someone who can write. ;)

We need more info, but here you go....

[ProppaT]

First of all, we have no idea what format the book is to be in (print, pdf, windows help file, etc). Each different format requires different software/knowledge. Without this information, it's pretty hard to recommend anything.

However, as a tech writer with years of experience, if you don't know much about writing or structuring manuals, I would probably default to the defacto FrameMaker package. It supports Docbook, unstructured and structured (SGML and XML) tagging, and it fairly easy to get going with. If you outgrow it's functionality, you can buy one of many packages for macro editing and automation of repetitive tasks. Adobe has a free program to help you do some of these things, but it's very similar to coding C and may be a bit overkill.

As a last resort (and if you have access to people who know how to create or modify a DTD for your use), you could buy a package such as Stylus Studio for editing code and creating XLST files for automating tasks and formatting the document. Unless you have experience, this will be overwhelming.

If you need online help, well, you'll probably use RoboHelp like most everyone else.

As far as any more advice than recommending the software packages, I think we really need to know the scope of this project (length of book, what type of information is involved, how much of the book is tabular data vs. instructional data, etc). Personally, I have about 5 different software packages at my disposal and use a each on a case by case basis depending on use.