DITA Meets Wiki – Output DITA to Wikitext

A few years ago I wrote a blog entry on talk.bmc.com about combining DITA’s structured authoring principles with wiki’s collaborative, quick authoring style. The subtitle is “Darwin Information Typing Architecture, Meet Wiki” and I think that’s still appropriate. For quite some time, it was in the top ten on Google when searching for “DITA wiki” and today it’s a respectable 3rd or 4th hit.

I’m pleased to report on my blog once again about the possibilities of DITA and wiki – by reporting that there’s an open source method for converting DITA source files to wikitext output and even populating the wiki itself when using Confluence wiki. Lisa Dyer of Lombardi Software has been using this technique for about four years now in production, and she has generously given back to the community by starting the DITA2Wiki open source project on SourceForge.

Lisa has two blog entries describing both the initial release and this week’s update release:

Currently, it builds to Confluence Wiki, but its framework lets you extend it further to more wiki engines. I want to get a MediaWiki conversion going next, and I have joined the project in order to contribute. It would be great to have others join in the project.

I downloaded the DITA2wiki files, downloaded and installed a 30-day trial of Confluence wiki, and had working output with only a few troubleshooting incidents (I kept forgetting to change the path slashes from / to \ on Windows for the ant build properties file!) All the instructions for getting it up and running are on the SourceForge.net wiki pages for the project. I’ll sheepishly admit these are the pre-requisites I needed before I got it to work, in addition to the Troubleshooting that Lisa already provides:

  • Ensure you have a Confluence wiki running on the computer you’re using DITA2Wiki to build the output.
  • Ensure the URL and password for the wiki is correct.
  • Ensure the paths in the guide.properties file are correct. The two paths I had to change were the location of the DITA source files and the location of the DITA DTDs from the DITA Open ToolKit.
  • Each time you modify a path in the .properties file for a Windows environment, remember that the slashes are opposite direction from a copy and paste of the directory structure give you on Windows.

If you’re interested in using structured wikis and DITA especially in a software engineering project, you may want to read it on the Wikis 4 Software Engineering site. In it we describe how development processes, especially those using Agile development practices, can be streamlined and efficient when a highly collaborative and motivated staff has the right combination of wiki collaboration tools and training with structure added to the design and test documents shared on an internal wiki. The case study at the end shows how wiks and DITA end-user documentation work to give end-users the top layer of documentation started way back in the design process.

11 Comments

  • Pingback: DITA Meets Wiki - Output DITA to Wikitext | just write click Writer River

  • Mary Ann
    October 17, 2008 - 10:35 am | Permalink

    This is great news indeed. I cant wait to get started on trying out the DITA2Wiki thanks for sharing the info.
    You mention it would be great to have others join the Media MediaWiki conversion.. would you be able to let me know how I might volunteer?
    Thanks and regards,
    Mary Ann

  • October 18, 2008 - 3:44 pm | Permalink

    Hi Mary Ann –
    I’d love to have help with a MediaWiki conversion portion for DITA2Wiki. I went to lunch with Lisa last week and lamented that SourceForge didn’t make it easy to join a project – see https://sourceforge.net/docman/display_doc.php?docid=759&group_id=1#projectjoin. It seems you just email Lisa to let her know you want to join. Specifically, we’ll need to write a new dita2wml.xsl for MediaWiki wiki text, and then figure out how to automate the population of the MediaWiki database with the wikitext. I originally was thinking of MWDumper but probably a direct database population would work better? Any ideas are welcome!
    Thanks,
    Anne

  • October 20, 2008 - 10:56 am | Permalink

    Hi Anne and Mary Ann,

    First: thank you, Anne, for your great post and helping to spread the word! And thanks, Mary Ann, for your interest in the project!

    It would thrilling if you could contribute the MediaWiki import/export bits. I’m building a better home page for the project to help folks contribute and join – but as Anne describes, you can join the project as a developer upon a commit to the source. I will be setting up the SVN repository with all the src soon, after which you can commit.

    Please ping me at lisa dot dyer@lombardi dot com if you have any questions about how to proceed.

    Just FYI, there’s wide-spread interest in a MW2DITA path as well because of the MW footprint within corporations – lots of content on the wiki needing to be moved into DITA to enable portable outputs etc – and this might also be an “easier” starting point (the conversion could prove to be simpler). And this would give you the XSLT to “flip” for the DITA2MW path:)

    Cheers,

    – lisa

  • October 23, 2008 - 7:28 pm | Permalink

    Hallo Anne
    Thank you for letting us know about this, and for the great overview. It’s a really exciting project, and fantastic that the guys have made it open source.
    Cheers, Sarah

  • Pingback:   Weekly links roundup by Communications from DMN

  • Pingback: Playing with DITA2Confluence « ffeathers — a technical writer’s blog

  • April 7, 2010 - 11:08 am | Permalink

    Hi Anne
    I’ve just discovered this post and your lovely blog. I’ve put a similar comment over on Lisa’s Sourceforge project, but thought I’d duplicate it here. Was there any progress with the DITA2Mediawiki initiative? It’s something we at Symbian would be interested in participating in, but it’s not clear to me where it’s at (if anywhere) and I haven’t found much through Google. Except you :o)

    Thanks in advance,
    Jo

  • Lisa Dyer
    April 7, 2010 - 11:32 am | Permalink

    Hi Jo,

    The short answer is, yes you’d have to initiate such a project. The interest in DITA2MediaWikiit has grown, if anything, but the number of people willing to do work to make it happen, hasn’t:)

    I believe I posted some implementation guidance somewhere, perhaps on the dita2wiki forum at SourceForge, or offline email. I will look for that and update you via SourceForge.

    Do let me know via SourceForge if you have resources to engage in this project. I will assist and guide where I can.

    – lisa

  • April 7, 2010 - 12:49 pm | Permalink

    Hi Jo – Thanks for asking! Lisa had the answers you seek – and I’d be happy to help you. I’m not much of a coder but I can test and I have a test Mediawiki installation. Feel free to drop me an email.

  • April 8, 2010 - 3:48 am | Permalink

    Hi Lisa, Anne

    Thanks for your swift responses – we really appreciate your help. I’ll continue the discussion over on SourceForge (here’s the discussion I started http://sourceforge.net/projects/dita2wiki/forums/forum/864448/topic/3665168) and will check back in with you both when we have more momentum behind this project.

    Best wishes, and thanks again!
    Jo

  • Leave a Reply