How Technical Writers Use Confluence and DITA XML
April 1, 2008 6:10 AM
Anne Gentle writes about a presentation on a customer and documentation wiki sourced with DITA topics by Lisa Dyer of Lombardi Software at the February Central Texas DITA User Group meeting. Lisa's presentation explores how the company is using DITA and a wiki as the framework for collaborative information development, both internally and with customers who have a support login.
First, what's DITA?
It stands for Darwin Information Typing Architecture, and, "is an XML-based architecture for authoring, producing, and delivering technical information." (Source: Wikipedia)
DITA was originally developed by IBM and encourages content to be created & organized by topics, then published in multiple formats like HTML, PDF, and online help formats used by Java-based projects, and companies like Microsoft and Oracle.
Lisa's Presentation
On the importance of starting with internal use only at first:
Lisa Dyer recommends a pilot wiki, internal only at first, to ferret problems out while building in time to fix the problems. Michele Guthrie from Cisco... also has found that internal-only wikis helped them understand the best practices for wiki documentation.
That way, when you open the wiki to the external community, the internal contributors from your organization are well-versed in wiki use and ready to help nurture the external community's growth. That last thing you want is the internal people just getting used to the wiki at the same time as the external folk.
On choosing an open source or enterprise wiki:
Lisa said to ask questions while evaluating, such as where do you want the intellectual property to develop? Will you pay for support? Who are your key resources internally, and do you need to supplement resources with external help?They found it faster to get up and running and supported with an enterprise engine and chose Confluence, but she also noted that you "vote" for updates and enhancements with dollars rather than, say, community influence. (Editorial note - I'm opining on whether you get updates to open source wiki engines through community influence.)
Anne's editorial note makes a good point. For Confluence, we have a public JIRA instance where anyone can raise an issue and others can vote on it - which helps the development team get direct feedback on what customers need. This is a good example of combining voting with dollars (when you buy a new software license or continuing maintenance) and community influence.
Lisa's talk also looks at topics like Getting DITA to talk to the wiki, creating a wiki table of contents from a DITA map, and some of the limitations and considerations to think about when starting a project like this.
Copyright © 2009 Atlassian Pty Ltd.
5 Comment(s)
Hi Stuart,
This sounds interesting. However, I wonder how the wiki content is reverted back to DITA XML. Wouldn’t it make more sense to have a solution, where the wiki content can be converted to DITA or Docbook automatically? Single source publishing, with Confluence as the source?
I am actually working on a confluence plugin, which exports a tree of pages to a proper Docbook document.
Let me know what you think about that, I’d be very interested to hear about your opinion..
-Stefan
By Stefan Kleineikenscheidt at April 2, 2008 7:59 AM
Stefan,
I think that's a good point, and an example of the kind of data round-tripping that's brought to light by projects like Lombardi's.
Personally I think your plugin sounds like a great idea - the more tools we have to move data in standard formats, the better!
Cheers,
Stewart
By Stewart Mader, Wiki Evangelist
at
April 5, 2008 5:07 AM
Hi Stuart, thanks for blogging on this! Stephan, thanks for your comment.
Using Confluence as the source system and round-tripping with DITA XML were definitely both considerations when we first embarked on this project. From our perspective, there are significant issues with using Confluence as the "CMS" (which it really isn't). The issues are primarily related to the outputs and the content development process.
Examples of issues you'll have to handle when converting from wikitext to a much richer information architecture such as DITA XML or docbook:
# semantics of the markup (and potential system dependencies on that markup)
# transclusion (conref)
# conditional processing (ditaval)
# consumption/processing of comments which the wiki engine handles as entities separate from the body content
It all depends on your particular output and process requirements. And in terms of governance, things like selective rollback and "where used" are trickier in a collaborative wiki environment versus a source control system.
As for round-tripping with DITA XML: Since we launched our system a year ago, we have more data - versus theories - about how our community is using the system and interacting with the content, and it's very revealing. I think there probably is a tipping point at which round-tripping becomes necessary or at least desirable. At that stage, more is needed than "just" the programmatic conversion back to DITA or docbook. It probably is a question of operational efficiency and maintenance cost more than anything.
For more context and ideas, take a look at the latest STC Intercom article (free PDF download) I co-authored with Anne Gentle and Michael Priestley.
On another note, we are working toward releasing our DITA2Confluence plugin to the Confluence community. Give me a shout if you are interested in collaborating - I'd imagine a fully packaged "round-trip" service with our combined plugins would be of interest to the community. You can reach me at lisa.dyer@lombardi.com or http://www.linkedin.com/in/lisadyer.
P.S. It would be fantastic if Atlassian folks could engage with us on this, too. Considering the huge market uptake of standards like DITA XML, I think it makes good business sense for Atlassian to identify the aspects of this plugin architecture that could be rolled into Confluence core. Plugins are wonderful - until you have to upgrade:)
Cheers,
- lisa
By Lisa Dyer at April 17, 2008 7:43 AM
Thank you for this interesting article.
I'm searching articles/tutorials about using contexts and revisions marks, do you know where can i find them ?
Thanky ou
By rédacteur technique at August 25, 2008 6:48 AM
A good cross-reference: Atlassian's own Sarah Maddox talks about how this has progressed on her blog here.
... and among other important info there - here's the link to the Source Forge project notes (and release).
Pretty great stuff here!!
By Ellen Feaheny at December 7, 2008 8:43 AM