Single Source Documentation Woes

From: Dave Jarvis (dave_at_nospam.net)
Date: 06/25/04 

Date: Fri, 25 Jun 2004 16:40:26 GMT

Hello,

I am about to embark on a new software project where we're allowed to
make life as easy, or difficult, for ourselves as possible. To this
end, I'm looking to develop (or steal) an architecture that would
provide the ability to single-source user manual documentation, PDF
creation, HTML-help generation, and command line application usage
information (without precluding the possibly of man pages). I'll
attempt a picture:

+---------+
| Content |
| SG/XML? |
+---------+
    |
    v
+-----+ +------+ +-------------+ +-------------+
| XSL |-->| TEXT |-->| C++ Wrapper |-->| Application |
+-----+ +------+ +-------------+ +-------------+
  | |
  | +-------+--------------+
  | | | |
  | v v v
  | +-----+ +-------------+ +---------------+
  | | PDF | | User Manual | | *nix Man Page |
  | +-----+ +-------------+ +---------------+
  |
  v
+-------------------+
| HTML Help Pages |
| (WAP, HTML, etc.) |
+-------------------+

For the application, the mark-up might look like:

<commandline>
        <group name="Assistance">
                <parameter>
                        <name>help</name>
                        <description>Displays this.</description>
                </parameter>
                <parameter>
                        <name>version</name>
                        <description>Displays the version.</description>
                </parameter>
        </group>
</commandline>

This would be transformed at compile-time into:

$ ./application --help
Application Name

Assistance
   --help Displays this.
   --version Displays the version.

Similarily, the same mark-up would generate the following text within a
PDF, or user manual:

Application Name has the following command line options:

+------------+-----------------------------------------+
| Option | Description |
+------------+-----------------------------------------+
| --help | Displays this. |
+ --version | Displays the version. |
+------------+-----------------------------------------+

Obviously, we could also generate man pages from the content. And there
is an understanding that the command line options would be sourced from
its own file, embedded (linked to) within a larger document. This
allows the developers to update the application without needing to
coordinate with the documentation people. For example:

<section>
        <title>Application Command Line Parameters</title>
        <para>
        Application Name has the following command line options:
        </para>
        <include uri="./application/commandline.xml" />
</section>

Where it gets tricky is with the HTML pages. Ideally, every page would
have context-sensitive help. However, some of the help is only suitable
online, and some of the help only makes sense in print. Still other
portions are only possible within a PDF (e.g., bookmarks). Some mark-up
(this is an off-the-top-of-my-head-example):

<section type="help">
        <steps>
                <step>Click the OK button.</step>
                <step visibility="manual">Wait 10-15 seconds.</step>
                <step>Type your first name within the name field.</step>
        </steps>
        <ref visibility="pdf" visibility="web">
                <para>Change your last name.</para>
                <uri>last_name.html</uri>
        </ref>
</section>

Whatever code is generated must be browser- and device-independent.
 From simple (X)HTML to trimmed-down HTML for WAP.

To make life truly entertaining, throw in on-the-fly multilingual
translation facilities for all aspects described above. I've already
developed an architecture, at my previous job, to automatically
translate XML documents from English into any language (they didn't
automate it, but ran my [ahem, "temporary"/"proof-of-concept"] scripts
to generate entire lingua-specific sites [on the order of 1000 pages per
site]). For technical details on how this was accomplished, please see:

http://www.joot.com/dave/writings/articles/xsl-multilingual.html

Comments, critiques, and additional ideas are most welcome.

So far we've looked at Adobe's FrameMaker and RoboHelp for FrameMaker.
I don't know if either fits the bill. FrameMaker looks capable. My
concern is that this might have to be a custom task, even though it
looks like something that should already be available off the shelf.
I've also toyed with the idea of using LyX combined with an extension of
DocBook (or other SGML/XML standard).

Thoughts?

Dave