There have been a number of posts on LinkedIn groups recently discussing the pros and cons of using wikis for delivering enterprise product documentation. These generated some lively discussion with members strenuously defending viewpoints on either side - some saying documentation wikis work fantastically, and others saying they are "categorically unsuitable" for product documentation.
My viewpoint (your mileage may vary) is that for typical use cases, authoring 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.
When a Wiki works
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 (i.e. metadata-based) search
- Analytics on content relevance / popularity / traffic
- Exposing documentation to web search tools (e.g. 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.
When a Wiki doesn't work
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, the creation of navigational aids like TOCs and related content, resizing / down-res'ing of graphics, integrity of hyperlinks, conversion of complex text and table formatting into wiki markup, mapping of metadata, etc.
- Inability to publish into other formats (e.g. PDF or various help formats). While some wikis enable output to some formats like PDF, the styling can be less than desirable without extensive work on the CSS. 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.
- Extreme difficulty in managing localization of content. Ask anyone who's tried it.
- Difficulty in integrating wiki content with other systems e.g. CRM (for customer profiling) or support ticketing system / 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. Tagging policies are difficult to deploy and manage. 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 occurs even on excellent technology platforms that met all of the content delivery requirements, and even when managed by highly skilled KM organizations.
Issues when publishing to Wikis from single source authoring environments
Publishing content into Wikis from a single-source authoring environment (e.g. XML or DITA) solves the issues of multi-channel publishing and localization, but introduces these additional issues:
- Round-tripping comments and user generated content (UGC) back to the single-source environment is very difficult or impossible and may require redundant information development / re-keying of content.
- Publishing single-source to wiki may require hand-crafting or tweaking content in the wiki environment for adding metadata, linking related content, etc.
- Republishing / 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.
Alternative approaches to Wikis
There are alternative approaches to wikis that address the remaining issues of CRM / support portal integration and curation of UCG 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 Heretto and XMetaL are integrated with social help platforms like the ones listed above. This enables round-tripping of comments and content ratings into the single-source development environment, easing the curation issues and improving the linkage to info dev.
- Social help platforms like MindTouch are integrated with support portals including Zendesk and Salesforce.com, and can replace the native KB tools in support portals, so you have one authoring environment and one source of the truth. MindTouch even enables support agents to easily convert answers to trouble tickets into KB articles.
- Some of these tools like MindTouch can also be linked to your web-based application to provide context-sensitive help.
- Publishing directly from single-source to the support portal knowledge base (i.e. 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.
