Wiki for tech pubs – ready for main dish status? Or still undercooked or side dish material?

Wiki Wiki Teriaki neon signWiki Wiki Teriaki neon sign, Austin, Texas

I’ve been doing some research for an article for the STC Intercom based on the interview I did with a friend of mine who does maintenance on the MOTO Q wiki. The article will come out this fall and I can’t wait to see if any rousing discussion appears on the STC forums. In the meantime, I want to continue to blog about wikis because I want to continue to research their use in the technical publications world.

I have had an interest in wikis for technical documentation for a couple of years now. There are a couple of good discussions on wikis for technical documentation from February 2007 on Tom Johnson’s I’d Rather Be Writing Blog as well as The Write Time blog. Tom’s post talks about using wikis to help with the documentation process. In response, there’s a wonderful entry by Lars Trieloff about exactly how a writer uses wikis for technical documentation.

While my STC Intercom article doesn’t talk about the internal wikis I’ve used for documentation tasks, as an Agile team member, I did find that the wiki housed information while development was ongoing and I also edited pages to keep them updated as I discovered something in the code that didn’t match the wiki.

It’s funny, in an early blog post I wrote on the internal blogs at BMC I said that I did not see how wikis would be used successfully for technical publications. I have since changed my once low opinion of wikis but I still see them supplementing other documentation, not substituting completely for technical documentation. I’d welcome discussion about wiki as standalone or supplemental end-user documentation. What do you think? Should the merits of wiki for certain products win out as the exact right documentation for that particular product especially one either related to an Agile methodology or social media? Or are wikis relegated to an upgrade to the customer support forum with a kludgey way of entering the information and no good method for outputting an information deliverable worth reading?


  • Pingback: Wikis in Documentation: Ann Gentle Asks, Can Wikis Stand Alone, or Must They Be Supplements Only? | I'd Rather Be Writing

  • June 27, 2007 - 4:07 am | Permalink

    Hi Ann,

    I made a comment/response to your post here.

  • June 28, 2007 - 10:08 am | Permalink

    I definitely don’t think a Wiki is viable as a standalone documentation repository. Unless, of course, you lock out most users from making changes but then you are countering the very principle on which Wikis are based.

    We use them internally at our company and it works well as a place to store unofficial content, some of which is then taken and filtered by the technical writers, before being published to the world at large.

    We may, someday, have an external Wiki to which customers can contribute, although the governance of such a thing is always the sticking point. Depending on your customer base, they might not accept a Wiki as being ‘official’ as it is not controlled and checked. Our product documentation is verified internally before being published, and that remains a comfort to our customers, I’m not sure they’d be happy if we didn’t offer that verification.

    In short, how many millions of pounds/dollars MAY be at risk if you have an open set of documentation and a well meaning contributor gets some code syntax wrong!

    They do have a place but, as you say, I think it’s very much a supporting role, similar to a forum or even a blog.

  • July 2, 2007 - 2:05 am | Permalink

    I think that there are many factors in the reliance on wiki for end-user documentation. As with other types of doc deliverables, a wiki’s necessity depends on the product being documented and the audience and consumers that need to read or edit the documentation.

    I think that the risk of litigation can be mitigated with decent policies. Think of the few amendments you’d have to your support forum policy if it were expanded to include your wiki. For example, if a user tries to help another user on your support forum, there’s an understanding that your company is not intending to lead another user astray. The largest companies such as Motorola and Microsoft have finessed their legal policies to allow for wikis. They’re large enough, though, that the positive PR and vibes they can generate from a wiki would outweigh the potential risk of an erroneous wiki entry being published for a small length of time.

    In time, depending on the technology documented by the wiki, the users may demand an open-edit policy on the documentation when very fast updates are required. Or users may demand the openess that a wiki offers. Time will tell, I suppose. I believe wiki use for end-user doc should probably be reserved for only certain suitable products and users.

  • Pingback: Contributing to wikis as a technical writer « just write click

  • Pingback: DITA and wiki - w/ho/w will (we/you) write « just write click

  • Leave a Reply