Harnessing user contributions for wiki-based documentation

Creating documentation using wikis or wiki-like software is inherently all about collaboration between various parties: programmers, testers, technical writers, and even informed users.  More than any other form of cloud-based collaboration, wikis are a natural way to enable your extended “team” to collect and organize their respective contributions to the knowledge already documented. This would be an ideal picture, except that users are typically not under your management or your company’s IP agreements; they have their own goals, and they tend to go after loose ends in the documentation in their own way. A strategy of “good fences make good neighbors” can help keep user-contributors engaged in your goals for improving the knowledge in your wiki-based documentation.

Fifty minds on the same goal--individually.

The legal approvers in your organization are probably most nervous about how to maintain a clear distinction between “warranteed” or standards-based information (that which has been through a formal approval process for intellectual property clearance and technical accuracy that the company will stand behind) and “user-generated” information (for which the IP rights may be unclear, or for which the information has not been approved by the programmers as technically sound or recommended).

One approach is to show both forms of information on a wiki page that clearly defines the authority of each set of content. Comment facilities are the obvious mechanism for getting and presenting the user contributions. Implementations can range from very simple, unmoderated posts to highly interactive discussions with product moderators involved in helping to guide towards best practices. Ideally, the implementation would have a way to encourage and recognize top contributors and to float the community-approved solutions into higher visibility, either by ratings or by active curation of the discussion into gems of knowledge.

A good example of this separation of standards-conforming content from user-generated content can be seen in the PHP programming language documentation. Although PHP is not a commercial product, its documentation interfaces are neatly differentiated–a model, in fact, for many commercial products! This function description is just one example:  http://php.net/manual/en/function.fopen.php . Note that the user-contributed notes are clearly separated from the approved content, which itself conforms closely to a standard template for the formal properties and interfaces of each language construct. Those parts don’t change except by an apparent internal and formal update process, whereas the users often challenge each other and offer alternative use case examples for other users experiencing similar issues.

In a quick look at other approaches, I see that the Perl Programming Documentation community (http://perldoc.perl.org/) seems to embrace direct user contribution with peer review, whereas the Ubuntu Documentation Team (https://wiki.ubuntu.com/DocumentationTeam) has a more central writing team but engages users extensively in forums. In both cases, a foundation or other formal governance structure represents “where the buck stops” on approving content that comes from user/contributors. The Mozilla and Eclipse foundations are also examples in kind. [And here I wonder, Have there been any studies of governance models for various software documentation efforts? It would be fascinating to see at a glance how the various compliance requirements of each such group affect the policies on how user contributions are handled.]

Coming back to the PHP example (which I like quite a bit, obviously), it is immaterial whether the authoring tool used by the tasked writers behind the public interfaces was a wiki or a traditional XML-based source and production system. User contributors interact only through a comment form provided for them, maintaining the separation of their contributions from the main reference material. The system is responsive, easily searched, and hugely popular among that community. Thinking about this model, I suppose that valued contributors who are not primarily tech writers could be allowed to interact directly in the source authoring application. One could acknowledge their authority and trustedness by granting them authenticated access to the governed content (probably requiring signed agreements as well). But other than the fully open Wikipedia system, I can’t find any example of products with warranteed information that permit direct user interaction with content.

So for content does not require legal/formal approvals for release, an open access wiki model like Wikipedia’s may fit your needs well enough, given enough eyes on the content to keep it trustworthy. But a well-implemented comment mechanism can  still make your customers feel connected and valued while keeping provenance in the content that you’ve put effort into reviewing, validating, and approving. If you can maintain a good separation between this approved content from whatever users may contribute, then the choice of how your trusted/extended team creates the governed content is more a matter of business strategy (for example, using XML standards like Docbook or DITA for content lifecycle management and for multiple outputs) and of company culture (providing wikis for programmers who utilize Open Source tools or Agile methodologies).

And there is no fundamental reason why a wiki-like interface can’t host XML-based content, for that matter. But that is another story…

Related readings:

  1. I hate “content”, http://www.janetswisher.com/?itemid=227
  2. DITA and wiki hybrids: they’re here, http://justwriteclick.com/2008/02/27/dita-and-wiki-hybrids-theyre-here/
  3. Creating DITA content with a blog or wiki, http://learningbywrote.com/blog/2011/04/creating-dita-topics-with-a-blog-or-wiki/
  4. What do you think about using a wiki for technical documentation? http://technicalwritingworld.com/forum/topics/what-do-you-think-about-using
  5. Building Exceptional Product Help Communities, http://www.slideshare.net/mindtouch/building-exceptional-product-help-communities
  6. and of course, Alan Porter’s book, WIKI: Grow Your Own for Fun and Profit


This entry was posted in News and tagged , , , , , . Bookmark the permalink.

3 Responses to Harnessing user contributions for wiki-based documentation

  1. Dick Johnson says:

    Don, I was reading your post on Wiki based documentation, and I thought you might like to see an example of DITA documentation published on a Drupal site that can also host user-contributed documentation. We just finished posting DITA content to our http://www.ditainfo.info site as a Drupal book outline.

  2. Don says:

    That’s so neat to see, Dick. I suspect that some of other sites I’ve looked at were also Drupal-based. One could support curated comments on any system that provides a rich enough API for the appropriate workflow and UI customizations. You’ve got a good example there, and your DITA expertise also shows in your content and blogs. Thanks to you and Anna!

  3. Pingback: Harnessing user contributions for wiki-based documentation | Global-Ready Content | Scoop.it

Comments are closed.