Is a Documentation Wiki in your Future?

Home/Publications/CIDM eNews/Information Management News 08.07/Is a Documentation Wiki in your Future?

JoAnn Hackos, PhD
CIDM Director
www.infomanagementcenter.com

Day One

Senior Information Developer: “I just spent four days updating the topics that explain how customers should create a new project. I’ve used three typical customer scenarios as the basis for the discussion, leading the readers through an analysis of their business goals, the selection of the best scenario, and the steps required to put the scenario into place. I think the topics are exactly what our customers have been asking for.”

Day Two

Customer Nerd: “I read over the new topics on creating a project. I think they’re a waste of everyone’s time. There’s only one scenario that makes sense to me, and it isn’t even on the list. I deleted all those useless scenarios, added my own, and changed the step-by-step procedures to match.”

Day Three –

Senior Information Developer: “Aargh! I just looked at the topics in the Wiki. Not only is everything changed, but the new content won’t work. If you follow these instructions (that is, if you can follow the cryptic content), you’ll end up destroying your database. I’ll have to put back everything that I originally wrote.”

Day Four –

Customer Nerd: “What happened to my stuff? I have to do it all again. What a pain. I see the note about destroying my database. Well, I tested everything and nothing bad happens. If everyone knows how to write a Java program correctly, they can get this to work. If not, they shouldn’t be using the product”.

In his Harvard Business School: Working Knowledge article, Sean Silverthorne describes the story of Andrew McAfee, an HBS professor who had his article, “Enterprise 2.0” targeted for deletions in Wikipedia. He learned that a group of people in the Wikipedia world, called “exclusionists” can create barriers to information. They can also change information to make it unusable, incorrect, and inaccessible.

Read the original article: How Wikipedia Works (or Doesn’t).

Information-development (ID) professionals have similar concerns about opening their content to customers who may not be deliberately malicious but who may have invented work-arounds that will cause problems for others. The ID professionals consider themselves responsible for the accuracy and usability of the content they produce; if customers change it, who then is responsible? If customers create content that results in data loss or even loss of life, where does the liability lie?

Inviting your Co-workers In (or Not)

In his interview with McAfee and his research colleague, Karim Lakhani, Silverthorne reports that the Wikipedia model does not transfer well to a corporate environment. They found that companies allocate resources to projects in a top-down manner. People are not necessarily free to contribute to knowledge creation that is the responsibility of someone else’s department. In information development, we are all too familiar with the difficulty of getting product developers, support personnel, or other subject-matter experts to review draft documents. Will we be any more successful at getting them to participate in content creation?

Only a tiny percentage of Wikipedia users ever contributes to the encyclopedia. However, since Wikipedia has millions of users, even a small percentage (much less than 1 percent), represents a lot of people. If you consider a similar percentage internally in your company, you don’t have a critical mass of knowledgeable people to work on the content. You may need a management push, i.e., required reviews, to get the system to work.

If your co-workers are willing to contribute to building the best content, you may want to invite them in. But be aware that the same problems you encounter with the review process are likely to occur:

  • reviewers who want something written their way (no revisions permitted)
  • reviewers who want the entire customer world to know how brilliant they are
  • reviewers who insist upon including the “theory of light” in the laser maintenance manual

On the other hand, if you do form a truly collaborative working group, you may be the recipient of real insights into the use of the product. If everyone can agree on the user personas, you can enlist the experience and wisdom of people who can advise the customers on best practices. I believe a collaborative environment in which experts share information is immensely valuable. If a collaborative environment using Web 2.0 technologies can facilitate knowledge sharing among qualified professionals in the company, it will be a remarkable success.

Will the Real Experts Please Stand Up?

Real expertise on using our products in a business environment exists among the experienced user community, not only in the company among the product developers and support team. For the past four years, I have watched the user community contribute to our understanding of DITA through user groups and collaborative websites like dita.xml.org.

I strongly recommend that the user community contribute to the design of information so that it meets their needs. If we can solicit user participation in a Web 2.0 knowledge community, we might have a powerful means for creating high quality content. But how should this process work?

In the OASIS DITA community, we use a Wiki for proposal development. Members of the translation subcommittee, for example, contribute comments to a new proposal available in the subcommittee’s Wiki. They make changes to the content following committee discussions. They clarify examples and add use cases to the content. The process results in a better proposal for future changes to the DITA specification.

A similar process could apply to the development of user content. Users could contribute to the development of use cases or scenarios of use, explaining the business needs that drive their use of the product. They could contribute to conceptual overviews that would help everyone understand how the business cases are best applied. They could comment on the step-by-step procedures, explaining what is unclear or unnecessary.

Lakhani remarks that ” … many companies are realizing that there’s lots of knowledge in the outside world and are asking, ‘How do we enable the outside world to interact with us?’ McAfee believes that students who have grown up with collaborative tools will expect to have opportunities to collaborate in the workplace using the new technologies.” But, Lakhani argues that technology is not the answer. Rather he points to the flow of information and the way that flow is architected to promote collaboration that is most important.

Like Wikipedia, we must determine what sort of collaboration will be most useful to the development of valuable content about the products we support. That collaboration might begin with an internal community and later extend to the external user community. We must also determine how the collaboration is best governed. Wikipedia has rules that determine how content may be changed, even if some of their rules seem to discourage participation. We need a new set of rules to govern how we collaborate so that we achieve the intended results.

Know that your customers are most likely creating their own information for their own purposes already. Know that many of your customers share information with other customers through emails, listservs, and websites. You cannot stop the process of collaboration. However, you can find ways for it to work to your benefit and to the vitality of your company’s products.

Take, for example, the technical writer who assumes that the software administrator needs instruction in navigating a menu tree. Detailed, step-by-step procedures that explain how to expand pluses and contract minuses take considerable time to produce, especially if accompanied by screen shots. With information from the trainers, the writer learned that the typical administrator is knowledgeable about software and operating systems. The menu tree is ubiquitous and requires no explanations. As a result, pages of explanation that the users would find useless and insulting were eliminated.

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close