we've used a custom solution to create user
documentation. Our markup is very simple and
very generic (no format-specific information like
font sizes or specific styles, etc.). This allows
us to target multiple targets that we can use
for our final document. Right now, we're targeting HTML, but we have done MIF and some
limited RTF (and could do other markups, including
XML variants, tex, troff, etc. if necessary).
The nice thing about a custom solution is that you
can tailor it to your needs. Our docs are structured
in a hierarchical man-page style tree, so we've developed a shorthand that allows easy
specification of links to other man pages.
One big advantage of a text-based markup is that
it is very easy (and quick) to make a change,
commit it to the CVS tree and regenerate the
target document. (I used FrameMaker several
years ago, and generating HTML output was a
painful process.
And of course, a text markup generally produces
smaller document sets (unless you include a lot of
images).
Another thing that we've done is to automatically
generate things like index pages (per section)
and a permuted index to the whole set. All of
these are simple tools under the control of
shell scripts or makefiles.
Slashdot Mirror
we've used a custom solution to create user
documentation. Our markup is very simple and
very generic (no format-specific information like
font sizes or specific styles, etc.). This allows
us to target multiple targets that we can use
for our final document. Right now, we're targeting HTML, but we have done MIF and some
limited RTF (and could do other markups, including
XML variants, tex, troff, etc. if necessary).
The nice thing about a custom solution is that you
can tailor it to your needs. Our docs are structured
in a hierarchical man-page style tree, so we've developed a shorthand that allows easy
specification of links to other man pages.
One big advantage of a text-based markup is that
it is very easy (and quick) to make a change,
commit it to the CVS tree and regenerate the
target document. (I used FrameMaker several
years ago, and generating HTML output was a
painful process.
And of course, a text markup generally produces
smaller document sets (unless you include a lot of
images).
Another thing that we've done is to automatically
generate things like index pages (per section)
and a permuted index to the whole set. All of
these are simple tools under the control of
shell scripts or makefiles.
See SavaJe docs for the results.
Ed