Manual Writing Tools? 139
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?"
How about Word? (Score:2, Insightful)
LaTeX (Score:4, Insightful)
Re:A spelling checker, for one (Score:1, Insightful)
Digital had a neat pattern (Score:3, Insightful)
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 (Score:3, Insightful)
We need more info, but here you go.... (Score:4, Insightful)
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.