Wikis in Documentation: Ann Gentle Asks, Can Wikis Stand Alone, or Must They Be Supplements?


Ann Gentle of BMC has been researching the use of wikis in documentation. Although wikis have been around for at least ten years, they are finally getting more attention. Ann writes,

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 kludgy way of entering the information and no good method for outputting an information deliverable worth reading?

My Response

Lately I’ve had the opportunity to delve into SharePoint 2007, exploring its wiki, blog, and RSS functionality in depth. I’m convinced that SharePoint 2007 is the tool that’s going to change the way enterprises view wikis. Right now wikis are mostly web tools popular among open source projects where remotely located project members contribute to the documentation. SharePoint 2007 provides the same wiki functionality wrapped into the secure SharePoint tool that corporations love.

Top Reasons Why Wikis Will Increase in Popularity

I’m not an expert on wikis, but so far this is what I’ve noticed using the SharePoint 2007 wiki:

  1. Wikis are fast. This is literally what wiki means in Hawaiian. I think I can complete a documentation project in two-thirds the time using a wiki instead of a traditional help authoring tool.
  2. Wikis change the perception of help. Let’s face it: online help has a bad reputation of being useless. Wikis provide a new format that can counter that perception and empower critics with the responsibility to act on their jabs.
  3. Wikis draw upon collective intelligence. Even if you only have a handful of contributors to the wiki, drawing upon collective intelligence from actual product users is invaluable. Just getting one edit can expand the usefulness of your documentation tenfold.
  4. Wikis are convenient. With wikis, you don’t need to attach files to emails, compile an online help file, transfer folders to a shared server, decipher edits on paper, or try to interpret Word’s track changes. Editing of the files by SMEs and editors is a cinch.
  5. Wikis give the impression of being up to date. Even if they aren’t, wikis have more life. You can update them on the fly. One minor update to a page can renew the user’s faith that the documentation is current.
  6. Wikis have tremendous potential in the enterprise. Think about all the documents that project members collaborate on in the enterprise. Wikis will make project teams much more efficient (and fun).
  7. Wikis are a curiosity that merits experimentation. Everyone I meet is curious about wikis. They look at them with a new-found wonder. That’s worth something.

Challenges with Wikis

I see several challenges that wikis pose:

  • Most users don’t have the mindset that they can contribute.
  • Wikis have limited single-sourcing ability (at least SharePoint’s wiki does).
  • If you correct or eliminate a user’s update, you might offend that user.
  • Simultaneous edits cause problems when saving the material.
  • Wiki tools are still fairly primitive.

SharePoint 2007’s Wiki Strength

Unique to the SharePoint wikis is the ability to create additional columns/fields for each wiki page. For example, you can create an additional column called Category and force the user to select one of a dozen categories from a drop-down box. You can also add a field that forces the reader to answer yes or no to the question, “Does this page need more work?”

You can then create custom views that sort the wiki pages by the custom columns you created. This ability to add your own custom metadata to wiki pages, and then sort by those metadata fields, provides a lot of flexiblity and power. It alleviates some of the strained organizational limitations wikis have, and allows you to provide information to users in a variety of navigational assortments.

Wikis are notorious for being scattered mazes of chaos. But if you embed the right metadata tags from the start, you can create enough views for a variety of perspectives to satisfy users.

Ann Gentle Podcast Recommendation

By the way, several months ago I listened to an excellent podcast by Ann Gentle called Exploring Information Technology. I kept meaning to post about it, but never did. I really enjoyed it, Ann. I hadn’t run across your name before. Thanks for linking to me — that’s how I discovered your (non-work) blog.

Other Wiki Resources

Just thought I’d throw in a few more wiki resources:

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • rick

    I’m not 100% sold on the idea of using wikis to produce end-user deliverables. I think the idea of community-generated content, while attractive on the surface, is a bit oversold (think of the 90-9-1 rule

    Rather, I think a wiki’s collaborative nature lends itself more for an internal use (i.e., during the doc-creation process) — allowing writers, SMEs, etc. all contribute, collaboratively, towards the final deliverable.

  • Alan J. Porter

    Here at Quadralay we launched a public wiki for our major product range a while back with the idea that it would:
    # Serve as a supplemental documentation resource.
    # Create a communication channel to developers and consultants.
    # Allow users to contribute their ideas and experiences in a structured manner.

    We opened it up to our developers, support team and internal consultants for them to post articles, answer questions, and add supplemental material. We also invited our user community to join and participate, including setting up a Projects area for them to share experiences. The idea wasn’t to replace the existing documentation, but to build a collective intelligence about using and implementing the products.

    Interestingly while the number of users who have signed up and contributed content is admittedly smaller than we’d hoped by now, we do see the wiki articles being referenced with increasing frequency on independent user group lists. So people are reading it, and using it as a passive resource. As you mentioned the contributor mindset is not yet prevalent enough to make it the fully interactive process that it has the potential to be.

    The other unexpected side effect is that we have come to realize that we need to restructure and rework some of our standard product documentation to reflect the type of content being posted and developed on the wiki. An internal project is now underway to make that happen so that the two sources of information will complement each other in a way that brings the best value to our customers.

  • Pingback: 한RSS()

  • Anne Gentle

    Thanks, Tom! I’m so glad you found my new blog and posted a response about wiki for tech doc. I hadn’t even done the official URL redirect yet (stay tuned to my BMC blog for why.)

    You’re right, wiki software was invented in 1995 and the adoption rate is quickly growing. I agree that others are noting passive usage by users of tech doc right now, but I think that could change with some incentive programs or with some method of bringing in nuggets of wisdom from customer support forums or… lots of ideas based on interviewing a bunch of people and reading lots of blog posts like these in my article coming out in September.

    Alan, we should go to lunch if you’re located in Austin. It seems like as soon as I submit my “final” version of my wiki article I find new examples of tech doc in a wiki. Your WebWorks Wiki is an excellent example and I intend to follow it as it gains traction (which I would say it is).

    Perhaps wiki for tech doc is at a tipping point. Let’s move the fulcrum. :)

  • Tom

    It’s hard to make judgments about the whole wiki debate without more research, case studies, and examples. It’s still too early to say what will become of wikis. Then again, I haven’t been doing the kind of research Anne has. Anne, any chance I could get a sneak peak of your article/research?

    If the project I’m working on is successful, I will definitely write more about it.

    One cool thing about SharePoint’s wiki. I added two fields to each wiki page: “Does this page need work? Yes/No.” And “Comments? (blank text box).”

    Then I created two views that showed all pages needing work and all pages with comments. Today a SME provided comments on a lot of pages (more than direct updates to the actual content). The SME was then able to interact with other SMEs about the comments. This would have been much more difficult with traditional methods. The wiki worked beautifully to collaborate on the content.

    I think many people are afraid to directly edit a page’s content, even if they know the content needs adjustment. They are more inclined to throw out a comment or question about it — that’s why I liked Mediawiki’s discussion tab so much. A lot of times you don’t want to change the content yet. You want to discuss its validity. Wikis that lack this feature won’t be as popular, I believe.

    I agree with Rick that internal use may be more powerful than customer-facing exernal use of wikis. This is partly because employees can add to the wiki on company time, while customers have to do it on their time.

  • Tom


    I just read the Jakob Nielsen article you linked to. What a fantastic article. Thanks for pointing that out to me.

    Johannes Strobel, a presenter at the last STC conference, talked about the Wikipedia paradox that the Nielson article mentions. (Here’s Strobel’s slides.) Wikipedia claims to be an encyclopedia written by the world, but in reality there are only about 1400 people who write 73.4% of the content. This is only 2% of all the users. See slide 19.

    From Nielsen’s article, this paragraph really caught my attention:

    Make participation a side effect. Even better, let users participate with zero effort by making their contributions a side effect of something else they’re doing. For example, Amazon’s “people who bought this book, bought these other books” recommendations are a side effect of people buying books. You don’t have to do anything special to have your book preferences entered into the system. Will Hill coined the term read wear for this type of effect: the simple activity of reading (or using) something will “wear” it down and thus leave its marks — just like a cookbook will automatically fall open to the recipe you prepare the most.

    Do you know how to do that? In a help system, how do you say, people who read X topic also read Y and Z topics? I have never seen a help system that does this, although I’ve often heard the idea bandied about.

  • Tom


    Thanks for sharing the link to the WebWorks wiki. I like the point you mention at the end of your comment —

    we have come to realize that we need to restructure and rework some of our standard product documentation to reflect the type of content being posted and developed on the wiki.

    This makes sense. If users are posting tips or information about topics not in the standard documentation, it says a lot about the current documentation.

  • rick

    Tom asks….
    Do you know how to do that? In a help system, how do you say, people who read X topic also read Y and Z topics? I have never seen a help system that does this, although I’ve often heard the idea bandied about.

    You can collect this information thorugh any sort of analytics program. For our “hosted” help systems deployed through a webserver, we can easily record clicks and navigation routes.

    Another alternative is to use a dynamically generated list of “see also” topics (similar to the “dyanamic help” function in an Eclispe help system.

    What I would __really__ like to see is dyanamic list of links built, not only from the current page’s metadata, but also from the users browse history.

  • Pingback: Wiki for tech pubs - ready for main dish status? Or still undercooked or side dish material? « just write click()

  • Sean Tierney

    I find the 2 biggest flaws with most to be the setup process and the weird syntax you need to know in order to author documents. One resource I might suggest is JumpBox – we have both Dokuwiki and Mediawiki JumpBoxes that take care of flaw #1 and elminate the setup headaches for getting a wiki running.

    We’re big fans of using wikis for documentation and actually use the wiki component of a Trac JumpBox internally for development and documentation of the JumpBox platform itself.

    I agree though that nailing the usability of the interface for wikis will be critical for them to cross over to adoption by non-technical folk.


  • Judy Horton

    At InfoPros we have done quite a lot of research about wikis and, while we do think they offer real value to certain kinds of homogenous communities of interest, we think they have some pretty serious limitations for content managment:

    They create and edit only html pages
    They don’t allow granularity
    Documents can be “lost” if they are not linked
    Quality of the audit trail depends upon the software used
    Minimal or non-existent locking and version control

    Additionally, they need dedicated editors to quickly spot errors and roll back to previous versions. They don’t allow for reuse and documents cannot be automatically formatted for other media.

    If you’d like to see our white paper “Strategies for Driving Down the Cost of Product Documentation: Wikis and DITA”, you can find a link to it at

  • Tom

    Judy, you make some valid points about the drawbacks of wikis. Thanks for pointing me to your white paper.

  • rick

    There’s also a good discussion on that asks a similar question: Is Using Customer-Accessible Wikis for End-User Documentation Gaining Momentum? (

    It includes a list of several sites that use wikis for customer documentation

  • Roland Jones

    I personally recommend TWiki ( for (internal) documentation. Between its ability to use metadata, forms, and templates, a documentation group could create an entire publication workflow (with the exception of easy output to print centric documents…which requires some concessions like using CSS to define a custom output format and moving from HTML to whatever end format is needed). TWiki is promoted as a “structured wiki” meaning that it is somewhere between a full CMS system and a traditional wiki and allows the creation of mini-applications without programming skill. I like being able to refactor documents into reusable components then creating libraries of content that can be included in any other pages within TWiki. The versioning system is good because it allows absolute links to past versions; meaning that if a writer included content via link+version then it is possible to get historically accurate documentation sets if required for legal or compliance purposes. Since TWiki is written in Perl it’s also not too difficult to find programmers that can add any specifically needed functionality. I’ve been using it for single-sourcing whenever possible over the last few years. TWiki plus a Google Search Appliance makes for a very versatile documentation system.

  • Tom

    Roland, thanks for the recommendation about Twiki. I know that Bill Albing and Rick Sapir over at use Twiki and rave about it. I use MediaWiki and have been happy with it. I’m curious how Twiki handles simultaneous edits from multiple users. That was my key reason for choosing Mediawiki.

  • rick

    Actually, uses TikiWiki ( — not Twiki. TikiWiki is wiki-based CMS (it offers wiki + blogs, calendar, security, permissions, surveys, categories, structures, tagging, etc.).

  • Pingback: A Web 2.0 Documentation Idea Gone Wrong | I'd Rather Be Writing()

  • geldexpert

    To me the name Wiki equals your statement: Wikis are notorious for being scattered mazes of chaos.
    After reading your Top Reasons Why Wikis Will Increase in Popularity, and after doing some research, I would like to add another reasons: it is possible to add a new skin/look-and-feel on top of a wiki. So a wiki doesn’t have to look like the world famous wikipedia.

    • Tom

      @geldexpert, To be honest, my enthusiasm for wikis is waning.

  • Pingback: Protect your domain name « Science Notes()

  • Pingback: Can wikis stand alone? « Science Notes()

  • Nannie

    I’m impressed, I must say. Seldom do I encounter a blog that’s both equally educative and amusing, and let me tell you, you’ve hit the nail on the head.
    The issue is something that not enough people are speaking
    intelligently about. I am very happy that I found this in my hunt for something relating to this.