Porting documentation to wikis: problems and possibilities

Curious about whether methods yet exist to easily port legacy documentation to wiki format, I looked around and found this screencast about WebWorks ePublisher's wiki publishing feature. ePublisher outputs to two wiki formats:

• MoinMoin Wiki
• MediaWiki (which has the richer text formatting of the two)

Good: Word

A strength of ePublisher is that it manages Word source as well as FrameMaker source, which is important for several reasons: tremendous amounts of legacy documentation is sourced in Word, most Help authoring tools output to Word, and Word is a good environment for macro-driven processing of such content, to prepare it for the wiki.

Bad: Security

However, wikis themselves have serious downsides for use as documentation. For example, if you're counting on being able to draft and stage content on the production wiki for a future release, most wikis lack the security you'd need to accomplish that. Yet popular wikis have endless numbers of extensions and plug-ins; here, for example, is a security extension for MediaWiki:

• MediaWiki Extention: SimpleSecurity

However, the page opens with this warning:

If you need per-page or partial page access restrictions, you are advised to install an appropriate content management package. MediaWiki was not written to provide per-page access restrictions, and almost all hacks or patches promising to add them will likely have flaws somewhere, which could lead to exposure of confidential data. We are not responsible for anything being leaked, leading to loss of funds or one's job.

Better: Wiki with content management

But not all wikis are created equal, and there are hybrids that combine aspects of wikis, content management, and document management systems. Joomla!, Drupal, and Confluence are examples of these. The good news with WebWorks ePublisher is that the new 9.2 release includes wiki output support to Confluence, which is a market leader in wiki-based technical documentation. This ePublisher release supports Confluence across these features:

• Publish and deploy
• Standard wiki markup
• Supports CSS and complex tables
• Wiki category markers

Since Confluence supports the ability to organize content by release version and control page-view access categorically, it is a platform that many technical publications could move to with success. Given Word source, ePublisher should be able to get an organization to Confluence in one step. I hope to find someone who's done it!

Update: Import Word directly

I found this forum thread: http://forums.atlassian.com/message.jspa?messageID=257313202

According to this, importing Word documents directly into Confluence seems the easier, softer way, that's much like importing Word source into Author-it:

"Use the Doc Import feature offered with the Office Connector. Doc Import offers an array of choices when importing. Large documents can be split based on the outline feature used in Word. You can import the Word document to become a wiki page."

Comments

[Lisa Joy Dyer]

Hi,

If your information assets are already in DITA format, there is an open-source project called DITA2Wiki which distributes a DITA2Confluence tool.

Here's a two-pager describing the DITA2Wiki framework (continuous publishing process and tool):

http://www.writersua.com/articles/DITA2Wiki/index.html

The References section links to the DITA2Confluence download on SourceForge, plus resources that illustrate the use cases in more detail.

Brief tool summary:
The DITA2Confluence tool enables you to implement a continuous publishing process from DITA to the Confluence wiki. It also provides some extra power that other tools on the market don't, such as conref (if you have conref in your DITA source, it is preserved in the wiki output) generating wiki pages with labels based on DITA metadata, and dynamic publishing based on rules (ditaval).

Or, you can just use it as a one-time operation to migrate your DITA assets to wiki, if that's what you want:)

This project is active and has a growing community around it if you need any help or best practices advice. To evaluate, download the latest distro and user guide PDF, unpack to your drive, install prerequisite software (Ant, JDK, and Confluence), and give it a spin with the sample DITA source files.

If you don't have Confluence, install the eval download from http://www.atlassian.com/software/confluence/ConfluenceDownloadCenter.jspa (takes about 15 mins to set up)

Some community experiences are shared here:

* http://justwriteclick.com/2008/10/16/dita-meets-wiki-output-dita-to-wikitext/
* http://ffeathers.wordpress.com/2008/10/26/playing-with-dita2confluence/

Hoping you find this useful,

- lisa

PS. If you're not yet in DITA, you can get there from Word or Framemaker or many HATs fairly easily, and a quick google exercise will yield webinars and other affordable resources to guide you.

[Mary Connor]

Those extra benefits (conrefs, metadata) may well make it worth a trip through DITA to get to Confluence. Thanks so much for the guidance!