Table of contents
- Initial Questions about Wiki Use
- General Articles about Wikis in the Enterprise
- Interviews with Professionals about Wikis
- Sites about Wiki Issues
- Commercial Sites that Use Wikis for Docs
- Non-commercial Sites that Use Wikis
- DITA and Wikis
- Collaborative Tools with Wikis
- My Use Case
Return to the list of Key Articles.
Initial Questions about Wiki UseThe first step is to determine whether you want to provide a collaborative mechanism that allows end-users of the documentation to edit and add to the content and if so, how much. Some wikis (like MediaWiki) are fairly limited providing only a wiki and a mechanism for setting up user accounts; others (like TikiWiki) are a package that includes a wiki as well as other tools. These toolsets are built on a database to provide a content management system that can keep track versions of modular content. Before deciding on using a wiki, try to address these questions:
- Do you want to allow users to participate, to contribute, to edit: it's a social media so it's different qualitatively
- Notice we said users with an "s" not a single user; so it's different quantitatively too. How to handle authentication of users (or do you)? legitimate users? how open, how social? (See Note 1 and Note 2)
- What about content quality and and reliability of answers? so it's different in terms of quality how to handle disputed material? how to maintain content quality? full time editor? (See Note 3
- How do you integrate it with the rest of the content (docs, FAQ, forums, knowledge base, etc.)
- Do you allow users to add anything and everything (personal comments?) have a reserved un-editable section?
- What about multiple languages? How about maintaining a section for documents in languages other than English, as on the Python site? How do you ensure the quality of those documents?
- How will you deploy, secure, and maintain the wiki? Who will provide technical (IT) support?
- Will this be the “primary facility to conduct work”, to conduct interaction with your customers?
- Will you host it along with the rest of your Web-based content or will you outsource it and let an independent group host it? - just as a Dummies book is published independently.
- How do you handle copyright and legal concerns? Who owns the content?
- What about liability?
- How do you implement good search and index? Will customer input be tagged; will they have to enter keywords and select the type of content they are adding?
- How do you distinguish types of data? (bug, new feature request, undocumented feature, customer-specific info)
- How do you deal with mandated styles in a product name?
- How do you support different types of media? - wiki is mostly text based, but allows pictures, but what about videos, screen-casts, Flash, etc.? what about reviews and feedback and comments on added content?
For the #2 item in the list above: herein lies a major problem with using wikis to create "community generated documentation": participation inequality. If too few users contribute, what's the point in a wiki?
— by rick.sapir on Jun 27, 2007 at 08:50 am
The MSDN Community Content information page says it has 3004 topics with Community Content, with 5884 Community Content Edits (see ClickOnce Deployment Overview for an example; the page includes a comment by a user who disagrees with a statement in the article). Of the 1876 contributors, 5 contributors (three from Microsoft) made about 1500 of the edits. Which backs up the Jakob Nielsen article that Rick cites.
— by betsy.kent on Jun 27 at 12:45 pm
Wikipedia, which is often heralded as the utlimate in wiki collaboration has a similar problem. By this account, 99.8% of its articles fail to meet its standard. — by admin on Jun 27, 2007 at 01:43 pm
General Articles about Wikis in the Enterprise
The latest article is Wikis Are Now Serious Business by Marshall Kirkpatrick (May 19, 2008) has several examples where wikis are used in a range of business settings (not necessarily end-user docs). It was published on the day that the free, hosted wiki provider Wetpaint announced that it has now raised a total of $40 million in venture capital. That's some serious capital.
The article by Ryan Singel, that originally appeared on wired.com, Veni, Vidi, Wiki starts the topic.
The enterprise wikis TWiki and Jot move beyond the traditional whiteboard sharing mode of a wiki by providing a platform where users can create simple, embedded applications within the wiki itself. These applications support basic business processes within a workplace; employees can track issues and call center status, manage tasks and reserve resources.
Wikis with the best technical features can still fail if the organization does not fully embrace their use. However, unlike open consumer wikis, in business they are likely to be used in the conduct of work, on specific projects, by people whose own interests are aligned with that of business. This is especially the case if, after the initial grassroots movement, management fully supports the wiki not as an optional, after-the-fact knowledge-sharing tool, but the primary facility to conduct work, …
Another Enterprise Blog and Wiki Success Story from Traction – Shore Bank
by Bill Ives
24 August 2007
Find out how Traction Software helped out ShoreBank.
Blog and Wiki Success Story from Traction Software - UK’s National Health Service (NHS) Orkney
by Bill Ives
August 23, 2007
Making Wikis Work at Novell
by Bill Ives
June 01, 2006
Find out how Novell uses wikis.
When to Wiki, When to Blog
by Bob Doyle, EContent Magazine
Promoting Internal Collaboration with an Enterprise Wiki
by Monroe Horn, of Bromberg & Sunstein LLP
in Peer to Peer magazine of ILTA (International Legal Technology Association)
Managing Wikis In Business
by Penny Edwards,
October 3rd, 2007
and see the full report (in PDF) at
Interviews with Professionals about Wikis
- Text: Dee Elling, a tech pubs manager at CodeGear, discusses wikis that she has maintained or managed. Interview about wikis for tech doc with Dee Elling of CodeGear
- Text: Emily Kaplan, a contract writer at Motorola, on the MotoQ wiki maintenance. Wikis for technical documentation, one writer's story
- Podcast: Harry Miller at Microsoft interviews Molly Bostic about the MSDN Wiki. MSDN Wiki - An Interview with Molly Bostic
- Podcast: Wikis Are Coming: An In-Depth Exploration of Using Wikis in Documentation an interview with Katriel Reichman (in Israel). He suggests that reference material is a good candidate for being on a wiki, while process-oriented and heavily-graphic material is less appropriate. He gives examples of how a good wiki will get user feedback or examples that will greatly improve the documentation. He also suggests that as wikis evolve, the tech writer's role may develop into more of an editor role, because many contributors expect that someone will clean up their text, and a designer role, including design of templates and process.
Sites about Wiki Issues
Here is a list of sites that explore wiki issues or provide a general overview of wiki use.
- EWeek had an article about wikis in the corporate world, which mentions Motorola as having over 3000 active (and apparently very useful) internal wikis, self-policed by the employees.
- wikipatterns provides a useful overview of issues that come up when establishing a wiki. It describes the common user types and suggests approaches to encourage participation, as well as editorial recommendations, such as including a Recent Changes and Contributors link. They have a very distinctive template for pages to help participants organize material.
- Shortest Path to a Wiki is a blog entry about helping a client choose the most appropriate software for a wiki that would replace an external web site. The article mentions considerations about open source support and ease of use.
- "Wiki Brainstorming and Problems with Wiki Based Collaboration" describes an attempt in 2004 to use a wiki as an open discussion forum for the students and faculty of an Information Processing class at the University of York. When it became clear that the wiki was failing because of lack of participation, the focus of the study changed to an evaluation of the causes of the failure.
- In 2005, the Los Angeles Times experimented with a wiki on their editorial page. Some readers used the wiki as the paper intended, providing contrasting points of view and adding links to supporting material. Unfortunately, other readers added foul language and pornographic pictures. The Times suspended the Wikitorial feature after three days. The registration process for the wiki was not strict enough to prevent the inappropriate entries. The L. A. Times is in the unfortunate position of being a universally cited example of what can go wrong with a wiki when insufficient thought and planning is done before implementing a wiki.
- 15 Productive Uses for a Wiki describes how wikis can be used for checklists, project management, and content management when users (or a user) need to access information from different machines.
- Enterprise 2.0 Podcast Archives provides links to podcasts of some of the presentations at the Web 2.0 Conference held in June 2007. Podcast topics include project management, using Web 2.0 on an intranet, and search capabilities.
Commercial Sites that Use Wikis for DocsHere is a list of sites that use wikis for customer documentation, in alphabetical order by company name:
- Adobe Labs has a wiki site where registered users can suggest content:
- Apache HTTP Server Project site, like some others, provides the "official" documentation as downloadable PDF or CHM files. They provide a Documentation Wiki for user-contributed tips and tricks for the Apache HTTP Server. The wiki front page suggests verifying material from the wiki with the official documentation.
- Apex Developer Wiki is a collection of documentation, samples, and tools to build on-demand applications on the Apex platform.
- eBay wiki EBay uses a wiki to for customer support information, allowing customers to post any information relevant to eBay. See Anne Gentle's article at http://talk.bmc.com/blogs/blog-gentle/anne-gentle/ebay-wiki.
- IBM RedBooks RedWiki - This is an experiment by the IBM RedBooks group to use wikis for user documentation. As with the Microsoft Community Content pages, contributors must register. They are using Confluence. Contributors can add new pages and request an editorial review. Recently, 27 pages were in the To Be Edited queue.
- IBM developerWorks - These wikis discuss a variety of topics. Some recently updated pages included instructors' materials, such as a PDF for a trifold quick reference card. As usual, registration is required to modify pages.
- iMIS - iMIS is an end-to-end solution that allows membership organizations to integrate critical business operations with ebusiness processes and Web site content management.
- Microsoft MSDN - In December 2006, Microsoft announced the availability of Community Content for the Visual Studio 2005 documentation, although not all topics are so enabled. The Community Content logo and link to add new material is on the bottom of the page (.NET Framework Developer Center) and is easy to overlook. To edit, you need to sign in with a Windows Live ID, such as a Hotmail address or Microsoft Passport. After signing in, you pick a user alias to identify your contributions, and accept a contribution agreement, which looks pretty standard. Unlike wikis like Wikipedia, comments made to the MSDN pages are separate from the original content (see ClickOnce Deployment Overview for an example; the page includes a comment by a user who disagrees with a statement in the article). The scrollable list box that contains the user data includes a history link, so you can see who updated the comment and when. This approach reduces the concerns over malicious vandalism of the content provided by Microsoft.
- Microsoft Sandcastle - Documentation Compilers for Managed Class Library has an active forum, but little other interactive content. It primarily refers the reader to other blogs.
- Microsoft Visual Studio wiki http://msdnwiki.microsoft.com/en-us/mtpswiki/default.aspx.
- Microsoft Channel9 hosts - a number of wikis and lists other Microsoft wikis sponsored by other groups. The page notes that the wiki search is broken, and provides a link to "temporary wiki search. One Microsoft wiki is the Channel9 Security wiki at channel9.msdn.com/wiki/default.aspx/SecurityWiki.HomePage. You have to be a registered Channel9 user to edit the page.
- Motorola Q - Motorola maintains the wiki (based on MediaWiki) for the end-user documentation for their Motorola Q phone. There is also a everything Q wiki also about the Motorola Q phone (based on WetPaint).
- PmWiki- This wiki provides a list of sites that use PmWiki for customer documentation.
- Quadralay WebWorks site. For users who do not log in, the pages have an "immutable page" note. However, more recently, they have added an errata page for users to report errors in the documentation. From the introduction on that page, it sounds as though Adobe had problems with well-intended wiki authors not reading the instructions carefully; as a result, access to the content files is more restricted.
- http://wiki.rpath.com/wiki/Main_Page - rPath has documentation for their cloud computing offering
- SeaPine labs - SeaPine Software has several wikis for their products.
- Splunk - Splunk makes indexing and search technology for IT infrastructures. Their wiki is a very general one for IT issues, not just their Splunk products.
- Technotopia - Techotopia is a library of free on-line IT books covering a wide range of topics including operating systems, programming, scripting, system administration, databases, networking and much more. Looks like they are using MediaWiki.
Non-commercial Sites that Use WikisHere is a list of non-commercial sites that use wikis:
- www.wikipedia.org is an online encyclopedia written and edited by volunteers.
- http://www.wikihow.com is a collaborative writing project to build "the world's largest how-to manual."
- http://www.ditawiki.org has the complete specifications for the DITA language and architecture in a form that supports comments and discussions.."
Open Source Sites that Use Wikis
- Sun Microsystems OpenDS (OpenDS.org.
- Eclipse.org coming soon.
Open Source RequirementsOne of us (rick.sapir) is currently investigating the use of wikis to produce and deliver end-user documentation for an open source (eclipse.org) project. Although user-contributed content is one of the stated goals, the primary reason for using a wiki is open source — I need a vendor-neutral solution — anyone should be able to contribute to the documentation without having to use a commercial tool.
DITA and WikisWith DITA (the "standard" for topic-based user-oriented product documentation) gaining wide industry acceptance, it's natural to wonder if the tools for have a DITA-based wiki will be available.Here are some articles about DITA and Wikis. (For background on DITA, see other articles on this site.)
- DITA and Wiki Combo http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-wiki
- A Web-Form-Based DITA Editor DITA and wiki and the possibilities offered by DITA Storm http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-storm
- DITA Storm, a browser-based DITA Editor by LogPerspective Inc. http://www.ditastorm.com/
- Crystal Ball: A DITA Wiki by Scott Abel http://thecontentwrangler.com/article/crystal_ball_a_dita_wiki/
Collaborative Tools with Wikis
Discussion of ToolsHere is a list of sites that discuss wiki tools:
- WikiMatrix maintains a comprehensive list of wiki software. They have a wizard that helps you identify what features you want in your wiki and then provides a list of the most promising products for your needs. If you answer "I don't know" to multiple questions, you get a very long list.
- Tom Johnson of TechWriter Voices made a short video on installing DocuWiki: http://www.idratherbewriting.com/2007/05/06/installing-dokuwiki
- www.wikispaces.com and ditacms.wikispaces.com describe simple wiki software that could be appropriate for a prototype project.
- Many companies that use SharePoint for sharing documents and content management may choose to use SharePoint's wiki capabilities as well. As with other tools, the SharePoint template can be modified to match other documentation on an intranet or Internet site.
List of Collaborative ToolsHere is a list of (virtual) community-oriented collaborative tools that may be used separately or in conjunction with each other:
- Collaborative Documents
- Email Lists
- RSS Feeds
- See the list of tools at scalefree.info
List of Virtual Community PackagesHere is a list of packages that provide a complete virtual community:
- From Anne Gentle: Gordon has a great angle on the usefulness of an internal wiki: http://www.onemanwrites.co.uk/2007/09/02/wikis-and-the-shifting-of-...
- From Anne Gentle: At Quadralay WebWorks, the whole company uses a wiki in many ways: http://www.slideshare.net/webworks/a-wiki-driven-company/
My Use CaseI (Rick Sapir) am currently developing wiki-based, end-documentation. The decision to use a wiki as the creation & delivery tool is base upon:
- The need for a completely open-source platform. We didn't want to impose any closed-source requirements (e.g., FrameMaker or RoboHelp) on potential contributors.
- The desire to allow any/everyone to contribute. Although I'm a realist and recognize the fact that most folks won't contribute, for the 1% that do, they can.
You can see the beginnings (the project is still in its incubation phase) here.
(more to come)
ConclusionThe wiki as a collaborative tools is gaining momentum and is in use in many settings. There is, as yet, no standard way to use a wiki, and each application of it is different.