Are structured authoring and wiki opposing forces?

It was one of those light-bulb-type discussions. Ideas popping and synapses firing. I had lunch with Chris Almond and Don Day this past week, discussing the potential authoring of wiki articles using DITA. We went through possible workflows, from a web-based DITA editor – to authoring in another tool and merely using DITA as an intermediary and transforming to wikitext.

If you know about DITA, you recognize Don Day as the chair of the OASIS DITA Technical Committee. Our lunch companion was Chris Almond, an innovative forward-thinking project manager. From him, I got the sense that internally at IBM, there is a perception of DITA as a technical writer-only tool to have in your toolkit. Chris coordinates and manages the authoring of IBM’s RedBooks, a very popular and technical set of documentation that are not product documentation but rather they show users how to implement a specific set of products, integrated together. He’s coordinating teams to do the scenario-based writing that applies the product in real-world situations. Many techpubs teams are striving towards use cases and scenario writing, and RedBooks are a great model for how to do it well. I know we tried to emulate it at BMC Software, and Bill Gearhart has an article about “Scenarios and Minimalism” in the CIDM Newsletter that discusses scenario and case study authoring.

Chris is trying to figure out how their current writing methodology and processes can be protected but also enhance the tools used and improve the resulting connections after the deliverable is written. Currently they engage with teams of authors to outline scenarios using mindmapping software and then divide up the actual writing assignments according to the author’s experience with the scenario. I immediately thought of JoAnn Hackos’ and Dan Ortega’s suggestions to have field personnel contribute scenarios to a product’s wiki when Chris described their process.

How do you actually empower the teams to write these wiki articles and assemble them into a useful (maybe book-like) wiki? Another question to Chris was, how do you layer an outline or table of contents on to the wiki, and then test and fold in any changes that wiki contributors make?

After at least an hour discussion I’m not sure we ever came up with the correct toolset. Or rather, there was a toolchain that could be used which is certainly do-able but not the ideal that he wanted to get to. I suppose one ideal is a DITA-based wiki with a web editor interface that would change editor strictness based on the author’s permissions. Authors who knew DITA and were most comfortable writing structured tasks, reference, and concept topics would get an XML-validating editor and authors that preferred more free-form would just use a rich-text editor that was nothing more than HTML headings, paragraphs, and lists underneath like what you use in Drupal, WordPress, or Blogger.

Suddenly it became apparent to me (but I won’t and don’t speak for Chris and Don) that some people are more determined to keep the editing quick and easy, but sacrifice that structuring and vetting step that structured authoring gives you.

This realization gives me a sense that there are two camps in technical documentation. There’s the “quick web” folks who connect easily and author easily, and then there’s the “structured quality” camp that requires more thoughtful testing and time spent on task analysis and information architecture. Also, the types of information that these authors are trying to capture are opposed in some senses. Then I thought a diagram might help.

wiki-fast-easy <-----------+-----------> DITA-difficult-tested

high-level scenarios <-----+-----> detailed dialog boxes

With such an easily diagrammed moment, you’d think I’d have an answer for the process we could use for a DITA-based wiki. Unfortunately it’s not quite refined, but I feel a step closer to understanding why this process is difficult to create – because the process is paved with these tradeoffs and apparent compromises and decisions you have to make along the way.


  • October 11, 2007 - 10:19 am | Permalink

    It’s an interesting little conundrum, isn’t it? I think part of the reason we’ve been pushing this concept as something that could show a quick value to the wiki sponsor is the operating context. The example of a field service technician is someone adding specific information on a transactional event that is already part of a producion workflow. This is not the traditional free-flowing wiki paradigm that most people are used to. If the authoring context is tightly contained (say what you want, as long as it’s about this specific topic), this should work. If authors have the ability to choose topic references when they create the content (maybe as part of a pull-down menu), the content becomes self-categorized. It would still need to go through an approval cycle, but having the contextual framework would make that process a lot easier and faster.

  • October 11, 2007 - 2:03 pm | Permalink

    So, just so I can continue to boggle my head with his, a layered approach to authoring would be the preferred route?

    I agree about the two main types of author, and your diagram neatly fits the point I was going to make, namely that an individual will slide to and fro along the scale, depending on what they are working on, why they are doing it and so on.

    And I’ll need coffee before I come back to this..

  • Pingback: one man writes » Recently Read

  • ffeathers
    October 12, 2007 - 9:11 pm | Permalink

    Hi Anne, Very interesting ideas. I particularly like the idea of putting a DITA structure behind a wiki – though for most users it would have to be hidden (scary). So we’d have a sort of object-oriented wiki page.

    And it gets even more interesting when combined with your use-case: asking field-operators to add scenarios which can then be collated into some sort of ‘book’ or other compilation.

    Some wikis allow you to create a template for a page. has a very simple one – when you add a page, the new page starts out with default content which you can choose to adapt or delete.

    If the scenario-authors followed the template, and if DITA or an XSLT conversion engine lurked in the background, we’d probably end up with some good building blocks.

    I’ve recently started using a wiki for technical documentation, and I’m really enjoying the wiki’s plus points as well as the challenge of finding work-arounds for its less techpub-friendly characteristics.

    Great post!

  • October 15, 2007 - 3:07 am | Permalink

    Wiki articles can be easily structured (see Wikipedia, for example). The greater problem, IMHO, is that you just can’t assign a writing task to someone that is not a writer. Our entire profession is based on the fact that people don’t like to write. (enough people to make a business case for us, writers.) There has to be a way to attract techical people to write, but asigning them with tasks has never worked for me.

  • ghkrause
    October 15, 2007 - 3:35 pm | Permalink

    I come from an engineering background with a drive to raise my voice and tell others what I know and think. But there are many engineers I know that prefer to sit on their knowledge. Some get tempted to write a Wiki article but it’s a pain to let the words go off into corporate playground. For those who like wiki but will not be technical writers we added a wiki2dita button to the system and wait for some articles to become mature enough to be transfered to the technical documentation domain. The import needs cleaning, indexing and tagging. If everything is fine the wiki article gets replaced by a link to the DITA CMS.
    This approach seems to be the opposite direction but it seens to serves as information development tool …

  • October 15, 2007 - 7:23 pm | Permalink

    Great comments, all. I am especially intrigued by the wiki2dita button – that seems like a good direction to go, capture the difficult to get info, but then clean, index, and semantically tag it to make it DITA-worthy.

    Gordon, I’m not sure if a layered approach is the preferred method, but it might be the only way to get otherwise reluctant non-tech writer contributors to put their thoughts or ideas into a wiki. I guess that the content is king, after all, it’s just us tech writers that want to take the content to the next level and protect it as a business asset and tag it and get it into other formats (like print.)

    And Avi, great point about how the added-value we writers bring is that we can write, and write well. Lately I’ve been lamenting my fading CSS skills, but I can still write. 🙂

  • Pingback: Odds and Ends | Idiotprogrammer

  • Leave a Reply