DITA and wiki hybrids – they’re here

Combinations - DNA and dice, relevant to Darwin?

Lisa Dyer and Alan Porter presented at last week’s DITA Central Texas User Group meeting, and both told tales of end-user doc written and sourced in DITA, with wikitext in mind as an output. About 20 people attended and we all enjoyed the show. I wanted to post my notes to follow up, and I’ll post a link to slide shows as well.

This post covers Lisa Dyer’s presentation on a wiki sourced with DITA topics. I’ll write another post to cover Alan’s presentation.

Although, actually, first, Bob Beims shared Meet Charlie, a description of Enterprise 2.0. Seems very appropriate for the discussions we’ve had at recent Central Texas DITA User Group meetings talking about wikis and RSS subscriptions and web-based documentation.

Lisa has made her presentation available online. My notes are below the slideshow.

DITA source to wiki output case study

Lisa Dyer walked us through her DITA to wiki project. Their high level vision and business goals merged with a wiki as one solution, and Lombardi has customers who had requested a wiki. Lombardi’s wiki is available to customers that have a support login, so I won’t link to it, but she was able to demo the system they’ve had in place since July 2007.

What wiki toolset – open source or entprise wiki engine?

On the question of choosing an open source or enterprise wiki engine, 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. I’m certain you can pay for support and enhancements to open source efforts with dollars.)

Run a pilot wiki project

She recommends a pilot wiki, internal only at first, to ferret problems out while building in time to fix the problems. While Michele Guthrie from Cisco couldn’t present on the panel at the last minute, she also has found that internal-only wikis helped them understand the best practices for wiki documentation.

Meet customer needs – or decipher what they want and need

Lisa said that customers wanted immediate updates, knowledge of what’s new with the product and doc (800 pages worth), and wanted to tell others what they had learned. She found that all of these customer requests could be met with a wiki engine – RSS feeds, immediate updates, and the ability to share lessons learned. At her workplace, customers work extensively with the services people and document the implementation specifically, and that information could be scrubbed of customer-specific info. They found that rating and voting features give good content more exposure. Also, by putting the information into wikis, they found that there were fewer “I can’t find this information” complaints.

Intelligent wiki definition and separate audiences for each wiki

They have two wikis – one is for end-user documentation, one is for Services information. In the screens she showed us, Wiki was the tab label for the Services wiki, Documentation was the tab label for the doc wiki. The Documentation wiki does not allow anyone but the technical writers to edit content, but people can comment on the content and attach their own documents or images. The Services wiki allows for edits, comments, and attachments. The customers and services people wanted a way to share their unsanctioned knowledge such as samples, tips, and tricks, and the wiki lets them do that. The Services wiki has all the necessary disclaimers of a community-based wiki, such as “use this info at your own risk” type of disclaimers. Edited to add: The search feature lets users search both wikis, though.

Getting DITA to talk wiki

There are definite rules they’ve had to follow to get DITA to “talk wiki” and to ensure that Confluence knows what the intent is for the DITA content. For one, when they want to use different commands for UNIX and Windows steps in an installation or configuration task, they would use ditaval metadata around in the command line text (using the “platform” property) and use conditional processing for that topic. However, because of the Confluence engine’s limitation of one unique name for each wiki article, they had to create separate Spaces for each condition of the deliverable (UNIX Admin guide or Windows Admin guide, for example). This limit results in something like 12 Spaces, but considering it’s output for several books for separate platforms, 32 individual books in all, that number of Spaces didn’t seem daunting to me. She uses a set of properties files during the build process to tell Confluence what file set to use, and what ditavals they’re seeking, and then passes the properties to the ant build task. The additional wiki Spaces does mean that your URLs aren’t as simple as they could be – but in my estimation, they’re not completely awful either.

While I was researching this blog post further, Lisa also added these details about the Spaces and their individual SKU’s (Stock Keeping Unit, or individual deliverable). “Building on this baseline set of spaces, each new SKU would add 1 to 7 spaces hosting 3 to 21 deliverables, depending on the complexity of the ditaval rules and the product. Obviously, the long pole in this system is ditaval. A more ideal implementation would probably be to render the correct content based on user preferences (or some other mechanism to pass the user’s context to the engine for runtime rendition). Or, a ditaslice approach where you describe what you need, and the ditaslice is presented with the right content. Certainly innovation to be done there.

Creating a wiki table of contents from a DITA map

She creates a static view of the TOC from the DITA map as the “home page” of the wiki. She currently uses the Sort ID assignment a DITA map XSLT transform to generate the TOC. She said they implemented a dynamic TOC based on the logical order of the ditamap by dynamically adding a piece of metadata to each topic – a sort id using a {set-sort-id} Confluence macro. The IDs are used to populate a page tree macro (the engine involved is Direct Web Remoting, or DWR… an Ajax technology). Currently, their dynamic TOC is broken due to a DWR engine conflict, which should be fixed in the next release. In the meantime, they are auto-generating a more static but fully hyperlinked TOC page on the home page of each Space. A functional solution, not great for back and forth navigation, but it shows the logical order which is pretty critical for a decent starting point.

Dynamic TOC created with sort-id attribute

DITA conref element becoming a transcluded wiki article

Another innovation she wanted to demonstrate was the use of DITA conrefs output as translusions in the Confluence wiki engine, so that in the wiki, the transcluded content can’t be edited inside of an article that transcludes the content. I don’t think it quite behaved the way she wanted it to, but knowing it’s a possibility is exciting. Edited to add: This innovation really does work, Lisa simply was looking at the wrong content (she admits, red-faced.) 🙂

Wikitext editor view of a conref referenced into a wiki page with a wiki macro

Burst the enthusiasm bubble, there are limitations and considerations

One limitation that I observed is that when you transform the DITA source to Confluence wikitext, there are macros embedded, so when someone clicks the edit tab in the wiki, they must edit in wikitext, not the rich-text editor, to make sure the macros are preserved. In the case of the Documentation wiki, they can instruct their writers to always use the wikitext editor. But, for the Services wiki, one attendee asked if users prefer the wikitext editor, and Lisa believes they do. Someone running MoinMoin at their office said they finally just disabled the rich text editor because they didn’t want to risk losing the “cool” things that they could do with wiki text. The problem at the heart of this issue is that if users really like the wikitext editor and do a lot of “fancy” wiki text markup (like macros), then another wiki user using the rich-text editor can break the macros by saving over in rich text. Edited to add: Lisa wrote me with these additional details which are very helpful – “actually, the macros are preserved when in Rich Text Editor (RTE) mode. the problem is that it looks ugly as heck – and if the user is not techie, potentially confusing. the RTE does add all kinds of espace characters to the content– in a seeming random way – and can negatively impact the formatting in general when viewing, but it doesn’t seem to affect our macros. However, if a user wants to use macros to spiffy up the content, then wiki markup mode is definitely recommended.”

If you’re interested in a copy of the case study, you can purchase it for $10 here:

Thumbnail of PDF

White paper, Structured Wikis in Software Engineering

This white paper describes using Darwin Information Typing Architecture (DITA) and wiki collaborative authoring environments in concert to enable software development processes including Agile development.


<div style=”width:425px” id=”__ss_301959″><strong style=”display:block;margin:12px 0 4px”><a href=”http://www.slideshare.net/lisa.dyer/lombardi-wikis-model” title=”Lombardi Wikis – a CenTex DITA UG panel presentation”>Lombardi Wikis – a CenTex DITA UG panel presentation</a></strong><object width=”425″ height=”355″><param name=”movie” value=”http://static.slidesharecdn.com/swf/ssplayer2.swf?doc=lombardi-wikis-model-1205252771520550-4&rel=0&stripped_title=lombardi-wikis-model” /><param name=”allowFullScreen” value=”true”/><param name=”allowScriptAccess” value=”always”/><embed src=”http://static.slidesharecdn.com/swf/ssplayer2.swf?doc=lombardi-wikis-model-1205252771520550-4&rel=0&stripped_title=lombardi-wikis-model” type=”application/x-shockwave-flash” allowscriptaccess=”always” allowfullscreen=”true” width=”425″ height=”355″></embed></object><div style=”padding:5px 0 12px”>View more <a href=”http://www.slideshare.net/”>presentations</a> from <a href=”http://www.slideshare.net/lisa.dyer”>lisa.dyer</a>.</div></div>


  • February 28, 2008 - 5:15 pm | Permalink

    Interesting post Anne. I’ve been going through a wiki reorg at work, and think you bring up a lot of good points. Nice to see we’re not the only ones going through similar things.

  • ffeathers
    March 2, 2008 - 3:55 pm | Permalink

    Hi Anne, great post! I’m really enjoying all the detail you’ve put into it.

    One interesting point is that Lisa’s innovative use of Confluence also shows one of the strengths of an opensource wiki: Lisa makes use of macros (the things in curly brackets in the wiki markup) which may be developed outside Atlassian. You can then choose to install such macros on your own instance of Confluence. A good example is the Multi-Excerpt Plugin which Lisa is using.

  • ffeathers
    March 2, 2008 - 5:45 pm | Permalink

    A clarification on my previous comment: It’s not entirely accurate to call Confluence an ‘opensource’ wiki. Rather, let’s use the word ‘open wiki’ — Confluence provides a plugin framework which allows third-party development.
    Cheers — Sarah

  • March 2, 2008 - 11:09 pm | Permalink

    Hi Julia, This post became a long, long homework assignment, so I’m glad to get some comments on it! Thanks for reading and commenting.

    Hi Sarah, it’s good to ensure you’re accurately portraying the openness of the Confluence wiki – there’s definitely a community aspect to the third-party plug-ins that feels open, and extensibility is important. So thanks for clarifying, and I do hope this example can be a good case study for your favorite wiki users, the technical writers! 🙂

  • March 3, 2008 - 12:52 am | Permalink

    A fantastic case study 🙂 I’ll come up with a post of my own soon (turning my Objectivism blog into an all-in-one thing 🙂

  • lisadyer
    March 11, 2008 - 10:59 am | Permalink

    Hi Anne,

    Thanks for your blog! And thanks, everyone, for your comments.

    For anyone who’s interested, I’ve shared my CTDUG presentation at http://www.slideshare.net/lisa.dyer/lombardi-wikis-model

    I welcome direct feedback and questions (my contact info is on the last slide).

  • Pingback: Atlassian Confluence @ WikiConsulting.com » Blog Archive » How technical writers use Confluence and DITA XML

  • April 1, 2008 - 2:54 pm | Permalink

    This sounds pretty interesting. However, I wonder how the wiki content is reverted back to DITA XML. Are the technical writers are doing that by hand?

    Wouldn’t it make more sense to have a solution, where the wiki content can be converted to DITA or Docbook automatically? (After a certain version of a page has been approved)

    Let me know what you think about that, I’d be very interested to hear about your opinion..


  • April 1, 2008 - 7:39 pm | Permalink

    Hi Stefan – great question, and that scenario is what I’ve talked to Lisa about as “wiki roundtripping” – taking the wiki source back to DITA source. Lisa says it’s technically feasible, but for now they are choosing not to. I’ll ask her to comment as well on their reasons.

    I’ve talked to Stewart Mader of WikiPatterns about wiki roundtripping, and we are planning a talk at DocTrain West on this topic. He says that when lots of edits start happening, people start asking immediately how to get the wiki to just be the “final” source so they can output from there instead of manually rolling the changes back into source from the wiki.

    Me, I’m still not certain of the best workflow or scenario. I prefer to write once and get multiple outputs, but that typically means there’s a “source.” I’d be happy with a roundtrip solution that lets the wiki be output and source at the same time.

  • April 14, 2008 - 8:30 am | Permalink

    Based on some recent experience, I am currently of the opinion that “round-tripping” is not a viable approach to using wikis from a product documentation perspective. Instead, the best approach is to consider your role as one of “seeding” the wiki with new content. But once the content is in the wiki, it should stay in the wiki from that point onward.

    I’ve recently been involved in setting up a fairly complex wiki for a colleague who runs a small music software company. I did so not in the role of an employee of that company, but as a user of their software, so I was able to see firsthand the value of user contributions to original company-authored documentation. Not as side articles on a separate wiki, but as edits to the original company-authored articles.

    When you include your internal development, marketing, QA, and Tech Support experts (not to mention those sharp cookies in your user community) in your authoring process, you can end up with product documentation that is 10x more robust and well-vetted than if you have only the tech pubs group authoring that stuff.

    I’ve seen concrete examples recently such as the following:

    1. I take a white paper that the developer wrote on a particular subject and turn it into several modular (and interlinked) wiki articles with my own “filling in some blanks” enhancements.

    2. The developer notices the wiki articles and the enhancements and is stimulated or “jump-started” to think about other enhancements and adds them himself.

    3. Another user is stimulated by the developer’s additions to make an addition of his own.

    4. I notice that the articles had been touched by two other people, take a look at the compares to see what they did, and I smooth out a couple non-parallel things in the new stuff and take a good idea that they introduced and apply it to some other similar articles.

    And so it goes. Real-time iterative improvements because the documentation source is no longer siloed under the sole control of one group. Everyone has equal access and equal ability to add their enhancements. I’m seeing developers get excited about the documentation… Passionate about making known some cool twist or tip they know about. All because they have easy access to the actual source. Everyone can learn wiki syntax pretty quickly, whereas using proprietary tools or just arcane syntax like DITA or some other XML standard tends to exclude everyone but tech writers.

  • Pingback: just write click

  • Drew Bray
    April 18, 2008 - 12:36 pm | Permalink

    As the writer at an open source software company, I really love the idea of roundtripping. We have “certified” content that we have integrated, tagged and tested and we want to include more community contributions that could be easily added to the “official” content through a wiki interface.

    I feel Shannon is spot on with her analysis of “jump starting” and “stimulating” documentation. The ease and familiarity of the wiki interface is just as appealing to our community users as our developers, hence the importance of roundtripping.

    Additionally, an RSS feed would allow me to see what has been added to and make my editing/certifying role much more precise.

    I am a bit skeptical of the technical feasibility and integration with CM systems but I am very glad to have found others of like mind!

  • April 19, 2008 - 9:32 pm | Permalink

    Thanks Shannon and Drew for your insights. At DocTrain West in a few weeks, I’m presenting about wiki roundtripping with Stewart Mader. Not that I have any answers yet, but I do have ideas. I think that the community you’re working with will have the most influence on the degree of roundtripping that you can do.

    I’m also taking Lisa to lunch next week to pick her brain some more! Her technological feats are quite impressive.

  • Pingback: Amazing conversations and meeting amazing people at SXSW Interactive « just write click

  • Pingback: From DITA to VITA: Tracing Origins and Projecting the Future | I'd Rather Be Writing

  • Pingback: Creating DITA topics with a blog or wiki | Learning by Wrote

  • Pingback: Harnessing user contributions for wiki-based documentation | Learning by Wrote

  • Leave a Reply