Just Write Click

I’m attending as many sessions as I can at the Quadralay WebWorks User Conference – called the WebWorks RoundUp. Right now I’m listening to a great demo using WebWorks to publish Word or Frame source files to wikitext.

Start with WIF

The WebWorks wiki defines WIF as WebWorks Intermediate Format – basically their Document Type Definition. Serendipitous search engine love for WebWorks. I hadn’t realized that when you Google “WIF” you’ll find there is a lot of academic call for the Wiki Interchange Format – a lowest common denominator of wiki content exchange. WIF defines a subset of XHTML as an over-the-wire format for wiki content exchange.

Keep it simple

He’s demonstrating the concept with headings and paragraphs only, but I would imagine that ordered and unordered lists would be simple, even nested indented lists are simple enough to mark up.

No tables, and I’ll admit, they’re a nightmare to markup in wikitext, so I sure wouldn’t tackle writing the XSLT to create tables from XML to wikitext.

Graphics you could create the wikitext for the file reference, as long as you take the time to upload the graphics to the location where the wiki is expecting them.

Generate the wikitext

He’s generating wiki markup using XSLT transforms that he has already set up.

Wikitext markup is really simple, using ASCII characters such as == heading text == to mark up a heading. In this example markup, more equals signs surrounding the heading indicate a deeper nesting of headings. Two equals signs indicate a heading 2, three === indicates a heading 3. Paragraphs are often not marked up at all, making them the simplest output of all. Refer to the wikimatrix.org’s markup comparison tool for more examples.

I would have liked to see examples of links and image references created, but this was an hour demo after all.

Put wikitext into your wiki

Finally, he’s copying and pasting the marked up wikitext into his wiki. For a long article where one page is one article, this approach makes a lot of sense. I could use a tool like this for the One Laptop Per Child project, where we have a Simplified user guide all in one wiki page. Each section is editable just because the wikitext is marked up using ==section name==, which is the markup for that particular wiki (MediaWiki).

And in his keynote the following day, Ben Allums demonstrated that he could publish to the wiki itself. Now THAT is an exciting development. I’ll dig deeper into the guts of that and report back.

Scenarios for converting to wikitext

I can think of plenty of scenarios for using this conversion process. Let’s say you need a hundred page user manual put into wiki format. This type of conversion would give you a huge leg up on the pre-population of a wiki with a user guide that is already in FrameMaker or Word. I would imagine you could somehow automate the webform population. For example, use IBM’s freely available CoScriptor to record the process where you create a new wiki page, then just run the CoScriptor script and paste when needed, then run another script that renames the new wiki page.

Because you can also publish directly to the wiki, but it seems to be in a way that doesn’t touch what’s already there, this method is a great way to continually update your wiki with fresh content.

Another great use of creating wikis with a conversion process would be for API documentation, especially if you already had a large body of work in a wiki. Let’s say you’re using DITA as your source file for your API, convert new portions to wikitext.

Any other scenarios for this conversion tool?