[Sigia-l] Customizable Documentation

[Listera]

"Berna_Tural at ibi.com" wrote:

> I am looking for usability and architecture information on customizable
> documentation.

Technically speaking, there are many ways to do this. Here's one system I
built about five years ago.

The basic concept: you have a DB of documentation parts, as granular as you
want to get. The DB contains unique IDs,  part titles, description,
creation/mod dates, and whatever other metadata you desire. This is
presented to the user as a (more or less regular) search engine that finds
the required doc parts. There's then a (hopefully) graphical tool that puts
in context all the parts the user selects and maybe allows him to edit,
re-order, etc. At  the end, the user has a Chinese menu of doc parts,
waiting to be collated into a single PDF file.

Now, PDF allows other PDFs to be embedded or concatenated. Since PDF allows
byte-range serving, you could even extract specific page-range of disparate
PDF docs into another PDF. However you do this, the idea is to collect all
those (PDF) parts to into a single PDF doc and return that to the user.

You could go fancy and convert other doc types to PDF, so you can serve a
wider range of documents. Or include in PDFs stuff like QuickTime movies and
animation, etc. You could also store your PDF parts in your DB as BLOBs. You
could construct the front-end to this in PDF also. You could create the
contents of the doc in real-time from variables, formulas, changing text,
screen-scraping from the web, etc. There's no end to this.

Since I design and develop stuff, I haven't looked at commercial stuff out
there much. But if you have an object-oriented backend the only tool that
works *directly on objects* to generate PDF and Flash is ReportMill. They
have been doing this sort of thing for a number of years with Apple's
WebObjects and now with other Java tools. For this, it's first rate, by far
the best and pricey.

<http://www.reportmill.com/>

On the lower end, you could build the search engine/DB part in just about
any language and assemble the PDFs via PHP, Perl, etc.

Dynamic documentation, it's about time :-)

Best,

Ziya