The Trouble with Delivering Product Documentation in Wikis—and Some Better Alternatives

Home/Publications/CIDM eNews/Information Management News 11.12/The Trouble with Delivering Product Documentation in Wikis—and Some Better Alternatives

Paul Wlodarczyk, easyDTIA
Used with permission from easyDITA

A number of posts on LinkedIn groups recently discussed the pros and cons of using wikis for developing and delivering enterprise product documentation. These posts generated some lively discussions among members strenuously defending viewpoints on either side—some saying documentation wikis work fantastically (even for authoring environments) and others saying they are “categorically unsuitable” for product documentation.

My viewpoint (your mileage may vary) is that for typical use cases, developing product documentation directly in a pure-play wiki product has major disadvantages compared to the available alternatives. Of course, as always, it depends upon the business objectives.

The goals that drive most organizations to consider a product documentation wiki are

  • socially-enabled content—building end-user communities around content, discussions/forums, content ratings, and comments
  • lightweight authoring tools for casual authors (whether end users or subject matter experts outside of a formal information development process)
  • dynamic content delivery in a web-based portal with semantic (metadata-based, for instance) search
  • analytics on content relevance, popularity, and traffic
  • exposing documentation to web search tools (like Google) so customers can find content easily

Wikis certainly achieve these objectives, but they create problems for information development organizations, whether the content is authored directly in the wiki platform or published into the wiki from a single-source solution.

Authoring content directly in wikis presents these problems:

  • Conversion of existing product documentation into wiki format presents issues with splitting large documents into smaller, more granular posts, creating navigational aids like TOCs and related content, resizing and managing the resolution of graphics, maintaining the integrity of hyperlinks, converting complex text and table formatting into wiki markup, mapping metadata, and so on.
  • Inability to publish into other formats (for instance PDF or various help formats). Wikis are largely geared for authoring content for wiki delivery. Publishing to other formats is limited, with PDF output largely for convenience. PDF styling can be less than desirable without extensive work on the stylesheets. Also, when you consider making the content available in modern formats like EPUB, mobile, HTML5, and other web formats, for all practical purposes the content is “trapped” in the wiki. Wikis are not single-source environments.
  • Difficulty in managing the localization process and multilingual source management.
  • Difficulty integrating wiki content into other systems, like a Customer Resource Management system for customer profiling, a support ticketing system, or a support knowledge base.
  • Content management and information architecture: It is very difficult to enforce information management policies in wikis. Wikis promote ROT (redundant, obsolete, and trivial) content by their very nature as social platforms. Tagging policies are difficult to deploy and enforce. Navigational structure is hard to define and maintain. Curation becomes very resource intensive and can easily become overwhelming. I have seen outstanding examples of corporate wikis that were initially successful—but once they went “viral,” they transformed into jungles of ROT in a matter of months. This outcome occurs even on excellent technology platforms that met all of the content delivery requirements and even when managed by highly skilled knowledge management organizations.

Publishing content into wikis from a single-source authoring environment (like XML or DITA) solves the issues of multi-channel publishing and localization, but introduces these additional issues:

  • Round-tripping comments and user-generated content back to the single-source environment is very difficult or impossible and may require redundant information development or re-keying content.
  • Publishing single-source to wiki may require hand-crafting or tweaking content in the wiki environment to add metadata, linking-related content, and so on.
  • Republishing or updating a wiki page from the single source environment may replace the wiki page and may purge user ratings and comments on the original wiki page depending upon the technology used.

There are alternative approaches to wikis that address the remaining issues of Customer Resource Management, support portal integration, and curation of user-generated content and comments:

  • Publishing from a single-source DITA environment to socially enabled help tools like MindTouch, DITAweb, or SuiteShare. These tools provide more control over end-user content creation and social content, easing the curation issues.
  • Single-source development tools like easyDITA and XMetaL are integrated with social help platforms like the ones listed above. They enable round-tripping of comments and content ratings into the single-source development environment, easing the curation issues, and improving linking to information development.
  • Social-help platforms like MindTouch are integrated with support portals including Zendesk and and can replace the native knowledge-management tools in support portals, so that you have one authoring environment and one source of the truth. MindTouch even enables support agents to easily convert answers to trouble tickets into knowledge-management articles.
  • Some of these tools, like MindTouch, can also be linked to your web-based application to provide context-sensitive help.
  • Publishing directly from a single-source solution to the support portal knowledge base (for example, publishing directly to Zendesk articles) solves the integration issues and may be a lighter weight solution that addresses the business needs for some organizations.

To recap, given the capabilities of the current generation of social-publishing platforms and the problems with managing product documentation in a wiki, I would hesitate to consider authoring product documentation directly in a conventional wiki.

Do you disagree—or do you have simpler requirements that are fully satisfied by authoring product documentation directly in wikis?