MediaWiki 2 for Printing and Documentation

When we create Product Design documents we include descriptions, requirements, test scripts, GUI mockups, and help text for each process step. We use RoboHelp conditional tags for each section, so the right information is outputted at the right time for the right audience. When we converted the RoboHelp files to MediaWiki with our RoboHelp2Wiki extension these sections become sub-headings on each article page. While we gained many benefits moving to a Wiki one important item was lost, the ability to output documentation. Printed documentation is still important for manuals, training materials, and sign-offs. Additionally, it would be very helpful to generate a hard-copy of the updated Product Design Document.

To solve these issues, I would need to convert over hundreds of Wiki articles into another format. Unfortunately, I have not found any good solutions for these conversions or the printing of Wikis in general. I have looked at the wiki2PDF scripts where user enters a list of articles and the script makes a single PDF file. However, it is based on the assumption I want to directly output the list of articles for final printing, which is not the case.

The ideal solution would be a new type of Wiki where the stored format can be used for multiple sources. A DITA based Wiki idea was floated and attributed to Paul Prescod, Group Program Manager, XMetaL in Crystal Ball: A DITA Wiki by The Content Wrangler and elaborated on by Anne Gentle in Document Actions Darwin Information Typing Architecture, meet Wiki. However, no such product yet exists.

Therefore, we are looking at reversing our RoboHelp2Wiki conversion tool to roundtrip the data back to RoboHelp. An advantage of this method is the ability to leverage the independent table of contents capability found in RoboHelp and other help authoring tools (HATs). Wikis and HATs have a natural connection between the HATs topics and Wiki articles. The power of HATs is the ability to organize the topics to best present the data. Organization is through table of contents hierarchies.

As part of the RoboHelp2Wiki conversion process the RoboHelp table of content hierarchy creates a MediaWiki conversion article. To roundtrip the information from MediaWiki back to RoboHelp, we simple need to create a MediaWiki article with the desired table of contents listing all the article pages and the order to present the information. On conversion, the tool would read this Table of Contents article and create the matching Table of Contents in RoboHelp and convert each article page listed.

In truth, we have been thinking about the above since before we created RoboHelp2Wiki, however, we did not want to commit resources until RoboHelp Version 6 was released. We were hoping that version 6 would be XML based without RoboHelp's priority tags ('kadov' tags). This is not the case.

So, before committing to a Wiki2RoboHelp strategy, we decided to look into creating the conversion tool to another HAT or editing tool. We plan to review Flare from MadCapSoftware and some of the DITA tools. We will also review the OpenDocument and Office Open XML. The minimum requirements would be ability to support an independent table of contents and the ability to round trip basic formatting, including tables. A nice to have would be the ability to round trip conditional tags.

Comments

[Paul Kandel]

I have been investigating the same type of approach. A robust wiki to online help tool that creates high-quality online help would remove a huge obstacle. It would also be very nice to have a tool to create man pages, and even PDFs with strong linking, indexing and bookmarks.
Another issue I have run into is conditional text. If we create content for multiple platforms and multiple product versions, how do we ensure that readers quickly and easily see the content they need? Do you know anything about this issue?

Thanks,
Paul

[FrankaPoto]

Hi,

Mothers Day is coming!

I just discovered a webiste with a hidden Amazon promotion page with low prices and great gift ideas for Mother's Day.

Check it out under http://bargains-hunter.blogspot.com/2008/04/mothers-day-is-coming.html

Cheers!