Structured Wikis and Software Engineering – Documentation Throughout the Process

Lisa Dyer and I have co-authored another paper about structured wikis, using DITA as the structure for the wiki. The paper contains specific ideas about using wikis both internally and externally for software engineering processes and software documentation.

Our assertion is this: While either waterfall development methods or Agile development methods could benefit from the collaboration a wiki offers, we believe that DITA typing combined with the wiki collaboration offers even greater benefits than DITA alone or a wiki as a standalone authoring environment.

We think this one is worthy of a price tag, so it’s available for sale here at Just Write Click. You don’t need a PayPal account to purchase if you click-through the links that don’t require you to login to PayPal, you just need a credit card. Once you purchase it, you’ll go to a page with a download link to the PDF file. We’ve discontinued the selling of this paper and thanks to those of you who purchased it, read it, and took off with the ideas!

You can now download the paper originally submitted to the Wikis 4 Software Engineering at WikiSym 2008.

We’ve revised it based on feedback from three reviewers who had excellent commentary and were not technical writers, so it should contain useful information for technical writers, developers, software engineers, business analysts, project managers, and quality assurance engineers.

5 Comments

  • November 5, 2008 - 7:40 pm | Permalink

    Hallo Anne and Lisa, Thanks for a great paper. It gives a very useful view into software development processes and the documentation produced by the development and QA teams in an agile environment. It shows the advantages of a wiki in such an environment, and how a bit (or a lot) of DITA-type structuring can help — even if it’s as simple as typing the content into the three basic types (concept, task and reference).

    And then of course, there’s the all-important area of user assistance. (That’s us, folks :) ) The paper describes how the structured wiki-plus-DITA setup facilitates the transfer of knowledge across the development phases and amongst the teams.

    Highly recommended reading :)

  • Dave
    November 6, 2008 - 8:00 pm | Permalink

    Hi Anne,

    Does your paper cover localization costs at all?
    The largest barrier for me to moving towards a wiki is the localization cost associated with allowing anyone access to change anything.

    – Dave

  • November 7, 2008 - 12:39 pm | Permalink

    Hi Dave,

    Are you thinking about localization from the perspective of hosting wiki content in multiple languages? Or edits to single-language wiki content by global community members?

    The former can be addressed with the model where information assets are maintained in DITA, and published to the wiki as part of a continuous publishing process (i.e. when updates are avail, publish again). In a multi-language content environment, you just publish once for each language set. Obviously, with this model, you are overwriting any page edits made by users since last refresh (comments remain untouched, which is important to note). But a good wiki lets you have control over who edits what and how those edits get processed further.

    If you are sourcing your content on the wiki in multiple languages, the solution gets trickier. I have not seen a wiki system in which you can target a set of wiki pages in one language, and then generate new wiki pages in other languages (presumably with a TM integration). The more structured your content model is, the more predictable are your results.

    The latter represents a quality issue to me. When users make edits to “warrantied” content, you want to make sure the language, style, and technical accuracy are what you require them to be. To some extent, this is a general issue with any collaborative information development: you might have some set or users in a position of subject-matter expertise to “code-review” the edits. Another approach is to provide a space for “unwarrantied” content, which is consumed as-is and as such less constrained. If you’re interested, there’s more information about these models in my slideshare at http://www.slideshare.net/lisa.dyer/lombardi-wikis-model.

    More than anything, it’s important to define the right *process* for your wiki solution. For the most part, with some tooling, you can make any wiki work for you in the way you need it to in a global environment – although some wikis are better than others.

    Hope this helps,

    - lisa

  • triona carey
    August 18, 2009 - 2:14 pm | Permalink

    Hi there

    Would be very interested in downloading this paper to share with information development co-workers but the link didn’t work!

    Is there an alternate download service?

    All the best

    Triona

  • August 18, 2009 - 9:21 pm | Permalink

    Hi Triona – Thanks for noticing that the link doesn’t work any more! I’ve changed the link so that you can download the link directly from my site instead of from the WikiSym site. Let me know if you have any trouble with the file, and I hope it’s helpful to you.

  • Leave a Reply