DITA as a wiki format?

Wikis for documentation make sense for many reasons, including  low cost of implementation, ease of publishing, and collaboration possibilities.  DITA has become a popular XML format for semantic markup of information and is generally used for documentation.  Wiki content is generally authored or stored as wikitext, which is an non-standardized markup format.  Should DITA be used as a markup format for wikis instead of wikitext or HTML? I believe the answer is that DITA in the authoring environment of wikis is impractical and does not work for general audiences.

I work at IBM where DITA was first invented and where we author an unimagineable amount of content in DITA. We create all kinds of tools to support its authoring, transformation, translation, specialization, and delivery.  DITA has in various capacities been explored as a format for a variety of delivery mechanisms, including content management systems, wikis, microformatted XHTML that retains DITA markup, and also your more standard outputs.  Basically, if some tool or application is out there, we’ve likely tried to make it DITA friendly.

Know your audience

You must know your audience to create quality documentation that meets the requirements of the user.  Most of my users are database administrators and application developers. My guess is that none of the users of the products I work on knows a thing about DITA markup.  DITA requires some upfront education for anyone that is going to create content in the desired manner.

A core feature of a wiki is the collaborative editing and authoring aspect. By using DITA as the wiki markup, you are removing that feature by subjecting your potential authors to learning a new language and all its nuances. The word wiki in Hawaiin means quick. Quick also implies easy.

Subjecting one of our users to DITA authoring would be a significant hindrance in terms of their ease in offering contributions. Public collaboration on most documentation projects is extremely difficult.  Tom Johnson in his article on A Few Surprises in using a Wiki for Documentation discovered that most contributors were likely to only make small edits rather than add to the documentation set. Why throw another roadblock in the way?

Editing tools

Last time I checked, there were very few web-based DITA editors. The primary contenders were DitaStorm, XMetal XMAX, and Xopus.  I have tried both DitaStorm and Xopus for working with DITA. DitaStorm seems to be the more generally well known web-based tool of the bunch. I’ve tried it through its various versions and my general feeling is that for very basic authoring it works okay but for more specialized authoring and design it is unwieldy and often buggy. Within IBM, we had a few licenses for a project and I often found myself wishing I was just using Notepad instead for editing topics. The problems and challenges I experienced I feel were more due to Javascript issues especially around cursor placement, but as an experienced DITA user found myself very frustratred to not be able to easily get the output I desired.

Most people author their content visually to create the desired elements and effects. When they want emphasis on a term they will use bold or italics. They won’t want to consider should that emphasized text be a UIControl, parmname, apiname, varname, or one of the many other semantic tags–they will use the non-semantic bold tag.

Solutions?

Do you try to hide the complexity of authoring in DITA from users that do not care and just want to write? Do you create a kind of hybrid DITA wiki that features some of the benefits of both worlds? Is a light-weight CMS really a better solution for easy authoring? Maybe a DITA to WordPress import plugin or to Drupal or Joomla?

Currently, I don’t feel there is a good answer for the human element of DITA and wikis. I responded to Tom Johnson’s blog post when it was first posted stating that I believe there is common ground between wikis and DITA but most of that common ground is in terms of technical implementation rather than usage patterns.

I am not saying there is not a place for a native DITA wiki, but the use case is probably for collaboration among DITA authors rather than with a larger community of end users.

7 thoughts on “DITA as a wiki format?

  1. I’m surprised to hear of the lack of DITA publishing tools. If so much DITA content is generated within IBM, what tools are used? Text editors?

    In the interest of serving technical writers and documentation teams, I’m very interested in the DITA/wiki connection. One option I’ve considered is a set of plugins to the rich text editors you often see in WYSIWYG wikis to support a bridge between the semantic DITA-style markup and the format tags used in HTML.

    -Matt W

  2. Hello Matt,

    I was referring specifically to web-based DITA editors. We use Arbortext Editor and a variety of IBM created tools to fill out the rest of the transformation and processing. We also have an information modeling tool that is available externally called IBM Information Architecture Workbench.

    There are plenty of desktop editors out there that make working with DITA quite easy but often licensing costs are prohibitive from making these available to people other than the information developers. You definitely do not want to tell your non-DITA users to just make the changes in Notepad =) Arbortext, Oxygen, XMetal, Framemaker are just a few with DITA support.

    It would probably be pretty easy to create a plugin for the TinyMCE editor or a few of the others that would give you basic DITA tagging.

    I would be very interested in seeing a demo of your wiki if it comes to fruition. Thanks for commenting.

    –Brett

  3. Hi Brett,

    At IOD Las Vegas IBM endorsed* four best of breed XML editors for DITA authoring: JustSystems XMetal and PTC Arbortext for power users, Quark for a Word based environment and Xopus for browser based environments.

    The last two tools are targeted at non-technical authors, so I can imagine that you as an experienced DITA author would prefer the more powerful tools. However, we’re adding more DITA specific features in Xopus 4.1 which may entice you to sacrifice a bit of control for a lot of efficiency.

    Feel free to contact me if you have Xopus specific questions or comments. I’m very interested in your thoughts about our software.

    -Laurens

    * Session 2459 Slide 13 available on: http://iod2009.confnav.com (account required)

  4. Hello Laurens,

    Unfortunately, I don’t have access to the IOD slides. I will download the latest version of Xopus, the last time I tried using it was version 3. I did not know about the latest plans for DITA compatibility with Xopus. That is exciting. I will definitely test 4.06 out soon. In addition to Arbortext, I also use a very simple web editor that I use occasionally for quick edits–will try replacing that with Xopus and see how it goes.

    I have an additional challenge with DITA though, we use IBM specific DTDs most of the time rather than the Oasis DTDs. They are related but ours often have additions that are not yet proposed or rolled out into the DITA OT.

    How challenging is it to add support for specializations beyond what is in the DITA OT?

  5. Hi David, Brett,

    Thanks for the interesting discussion. I just ran into this discussion on another blog. Check out http://everypageispageone.com/2012/02/24/frankenbooks-must-die-a-rant/.

    I haven’t checked out mylyn yet, but I think I will, and it will be interesting to see how it works with confluence (and JIRA). If mylyn breaks a wiki page down into components that can stand on their own inside a DTD specialization and provides easy-to-use functionality for migrating links to reltables, I think professional and freelance writers will naturally gravitate towards it.

    Daniel

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>