TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Carla says:
=====================================
Content
is not yet in a database, but the more I look at it the more
possibilities I see for manipulating it if it is. So that's where I want to take it.
I've no familiarity with any of those programs you listed.
I
had a quick discussion right after my initial post with one of our
programmers...
almost all of that content is in our SBM/TeamTrack
application that the developers
use. (SBM by Serena.) Not necessarily in user-friendly format, but it's there.
I may be able to hook into
that database and publish directly from it, but
that requires
additional research. If I can have it generate formatted reports
on
commands, that's 90% of my work.
=====================================
You're absolutely right -- If you can generate a report you're well on your way. You have options:
* Chances are you can generate XML, and then set up a Maker structure
app to import into Maker. Then your generated report is your documentation.
* You generate XML that makes each language entry a DITA conref source,
and create DITA topics that bring these conrefs in where you
want them. Sort of like using snippets in RoboHelp. This way you
can mix authored and generated documentation.
* Similar to the above, you could put markers into your document
to identify which XML report segments you want, and write a
FrameMaker extendscript to bring them in. Or something like that.
The point being, you get the same effect, but without the overhead of DITA.
* You could write (or get somebody to write) a bridge to your database,
and put database calls into your document -- the bridge would expand
them out to proper content in your doc. I'm talking about an FDK client
that makes the calls to your database.
I don't know about doing this for RoboHelp or MadCap. One thing you might be able to do is generate individual topics as reports from your code database, and bring them into your project. Or you might be able to generate the report as a collection of RH snippets, but I think it's not easy to import external data into a snippets database in RH. Somebody please correct me if I'm wrong.
I understand other peoples' call for you to investigate existing code documentation tools. I understand why you want to use the database -- It sounds like your developers already do that, and you want to be as compatible as possible. But you should at least be aware of tools like JavaDoc and Doxygen. If nothing else, you will better understand why the database solution is worth the effort.
But one thing that gets my goat is asking question X, and all the answers are, "You should probably do Y instead." Arrrgh!!!!!!!!!! I certainly hope I haven't done that!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>From our sponsor Doc-to-Help: Want to see a Doc-To-Help web-based Help sample with DISQUS for user commenting?
