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.