Recently we’ve been spending a lot of time writing the SDK documentation for the next
release of our product. As none of us is really that into techical documentation,
our first plan was to just write everything plain-text, in notepad (or Emacs in my
case) and hand off the text files to someone else who can do nice formatting, tabelization
(is that a word?), diagrams and such.
However, once the first draft of the actual text was finished, we wanted to see it
with at least a proportional font and proper headings, so we started thinking that
maybe if we used some special marker to signal headings, we could write a script that
would turn it into HTML (we didn’t want to write actual HTML by hand as it’s too much
tags everywhere, particularly <p> tags all over the place).
So, while thinking about what marker to use and how to write the script, it dawned
upon os that whatever we would do would end up very similar to a Wiki formatting engine.
As we use Openwiki for internal documentation
and ”knowledge capture”, I tried downloading it to see if we could make it to work
in a non-IIS context.
OpenWiki actually has an ”embedded” mode, but it’s made for embedding into other ASP
applications, and we wanted it to be used as a command-line vbs script. After some
heavy mangling I got it to work. The resulting WikiTranform.vbs is 274 kb large…
🙂 The end result looks so nice I’m thinking of suggesting that we ship the documentation
in HTML form (as opposed to FrameMaker-generated PDF).
Another option would have been to use Textile,
but since we’re already familiar with the (Open)Wiki style of formatting, this is
probably easiest.
I should pack it up and send to the openwiki guys, unfortunately the required mangling
was pretty rough, so it’s not that easy to fold the changes back into the mainline
source.
