Monthly Archives: July 2006

Embracing the Wiki Way: Deploying a Corporate Wiki

This article originally appeared in Freepint Newsletter 210.

Wikis, currently one of the biggest buzzwords in online publishing, helped solve a problem for my company, Ingenta. We needed to share information between the research and engineering departments, and we needed a simple tool to manage our rapidly growing set of references on key research initiatives and topics relevant to Ingenta’s core business area: offering technology services to academic publishers. I had created a wiki for myself to support my research and development role back then, and it seemed natural to expand it into an intranet alternative that allowed Ingenta’s users to edit and contribute to content collectively.

Now, four years later, Ingenta’s wiki is extremely popular. It has grown from one department to the entire company. We have even created wikis to interact with our clients as an easy means of sharing information.

Many companies are exploring the use of wiki environments, pressing them into service behind the firewall as a way to capture knowledge and improve communications within a business. Creating successful social software systems isn’t an exact science. Case studies and experience reports provide essential background when considering the success factors.

Deploying a wiki involves more than just selecting and installing an appropriate software package. They’re quite different beasts to the typical enterprise groupware or intranet application. They eschew rigid notions of hierarchy and permissions, letting users quickly create and shape a knowledge-sharing environment that supports them. Wikis are social software. Creating a wiki environment is as much of an exercise in community building as it is in software installation.

With this in mind, the first section of this article outlines how I introduced the Ingenta wiki. My aim is to present some tips to help other organisations deploy a corporate wiki, and to give them advice on creating a wiki culture.

Establishing need: the Ingenta corporate wiki

Having undergone rapid growth through several acquisitions and a major re-engineering project that resulted in a new platform for our core products, Ingenta needed a way to quickly capture and share knowledge. Turnover of contract staff necessitated a good knowledge-capture environment. The infrastructure to support these needs had not grown as rapidly as the company itself. Information was often in silos created by various teams using different tools and technologies. Grander visions for a corporate groupware solution were still on the horizon, but the engineering department needed something more immediate.

The idea of a wiki environment especially for the engineering team was natural. Already comfortable with web-based environments, they were also capable of installing and maintaining their own wiki. But while their ability to quickly learn the wiki functionality certainly contributed to the rapid success of the experiment, the more critical issue was that the wiki met immediate needs.

The environment worked well across increasingly distributed teams. The barrier to entry to contribute to the wiki is very low; documentation could be added and maintained very easily. Finally, the team already had a need to pass documentation around for review and sign-off. Requesting and incorporating changes became much easier as the wiki captured discussions directly rather than being lost in email. Reviewers could correct text and check revisions using the wiki change history.

Expanding the experiment

The wiki became a formal part of the engineering process after its initial success. All deliverables are now authored directly as wiki pages. Engineers use wiki pages to list current work priorities and capture the requirements for each project and incorporate release and testing documentation. The wiki also links to other internal tools and information sources. For example, release documentation links directly to our web-based bug-tracking system.

The initial growth of the wiki was almost viral. With little evangelism, the tool gradually expanded its user base to the rest of the company. It became natural for other departments, such as product management, to begin using the wiki. Users required little training to get started, since writing a wiki is as easy as writing an email. They also increasingly used the wiki as a daily resource, as the content was already closely aligned to many existing business processes.

Knitting together other sources of information using the wiki proved simple. For example, our shared network folders are web accessible, as are a number disparate tools and documentation. It was easy to create an intranet page in the wiki and link to these resources, creating a simple resource directory.

Today the wiki is actively used by every department, with the exception of finance. Perhaps I can tempt them away from their spreadsheets with wikiCalc <http://www.softwaregarden.com/wkcalpha/>! A reasonable number of users actively contribute new content and update existing documentation, while a larger group of users simply use it as a reference resource.

We’re now evaluating whether we’ve outgrown our current wiki platform and are looking at possible alternatives.

Choose your wiki

The obvious first step is to select some wiki software to use. The two biggest features I consider essential in a wiki are version tracking and search. Strong search facilities become particularly important once your wiki reaches a certain size.

In all, there’s a huge number of different implementations <http://en.wikipedia.org/wiki/Wiki_software/> to choose from. These range from simple no-frills versions to complete content-management systems. We opted for JSPWiki <http://www.jspwiki.org/>, as it meshed well with our existing technology platform. Another popular wiki is MediaWiki <http://mediawiki.org/>, which currently supports the Wikipedia sites and has an active user community.

There is also an increasing range of enterprise wikis such as Socialtext <http://www.socialtext.com/>, Confluence <http://www.atlassian.com/software/confluence/> and JotSpot <http://www.jot.com/>. Each offers a good range of features and commercial support options. You’ll need to take time to evaluate and experiment with a few different options. Migration between platforms isn’t always easy, as many wikis differ in features and syntax.

Build your community

Next you need to start building your wiki community. Start small. Focus on one or two teams initially. The wiki will need shepherding through its infancy, so nominate someone as a champion to help train staff members and guide them on how to get the best from the environment.

The best training exercise is to simply encourage users to wade in and start writing pages. We initially promoted a ‘sandbox’, or personal homepage, as a safe environment to play with wiki editing. More recently we’ve been encouraging new joiners to create their initial wiki page as part of their induction. This gives them familiarity with the tool from day one.

You’ll find that many users don’t always feel comfortable with editing existing content. Using a sandbox lets them build confidence before embarking on contributing to the main content.

One technique to introduce users to aspects of the wiki syntax and subtly encourage the view that the wiki is a shared environment is to edit someone’s homepage yourself. For example, I might tweak the page to make their email address a hyperlink, or just improve the display of their personal information. Letting them know that anyone can freely edit and tidy the information in a wiki is the most important point for users to grasp. It’s also the one that takes the longest to learn.

Stay relevant

Attempt to find or suggest ways for your initial community to usefully apply the wiki. Ensuring that the wiki meets a need and has relevant content will encourage sustained usage. Here are a few of the different ways that I’ve observed the wiki being used at Ingenta:

  • As a user directory. Most of our staff have a personal homepage including their contact details and current assignments
  • As a personal notebook to capture to-do lists or useful personal notes
  • For recording minutes of meetings. Rather than write up and circulate meeting notes by email, we often now make notes directly into the wiki
  • Managing information on clients, both current and prospective
  • Brainstorming new product features
  • Publishing documentation for both internal users and external clients
  • Capturing technical documentation on our products and services
  • Creating glossaries of terms. Every company and industry has jargon; we often define terms as separate pages in the wiki, enabling links to be added to documentation for clarification.

Avoid attachments

Some die-hard users insist they can’t possibly live without a word processor and say that a means to attach Word documents or spreadsheets to wiki pages is an essential requirement. Attachments are a useful feature for attaching diagrams or additional documentation to a page, but you should discourage overuse of attachments. If the useful content is in an attachment, then it’s not in the wiki and not easily editable. That’s not the wiki way.

Lay down pathways

Initially, we divided our wiki into people and projects. Pages were also introduced for teams and departments. These pages provided a basic organizing principle that became the primary means of navigating through the wiki. A similar structure would work in any corporate wiki.

However, these initial pathways provide more than just navigation. A wiki grows by people adding new links and pages to existing content. Your initial structure provides a cue as to where new content could or should be added. By introducing this structure from the start, you’ll help avoid the wiki deteriorating into a morass of interlinked pages.

As your wiki grows you’ll need to continue to organize it to reflect the needs of users and the growing body of content.

Employ a gardener

‘Wiki gardening’ <http://c2.com/cgi/wiki?WikiGardener> is a phrase used to describe tending a wiki to ensure that it stays fresh and remains navigable. Your wiki will need a gardener. During the early stages of deployment, you’ll manage with just a single ‘WikiMaster’. His or her role will be to lay down some of the initial pathways, tidy up pages and ensure content stays relevant. As the wiki grows, this role will become more than a one-person job. At Ingenta a number of my colleagues quickly embraced the wiki and became good WikiCitizens <http://c2.com/cgi/wiki?WikiCitizen>.

Typical wiki gardening tasks include:

  • Tidying up and re-formatting pages to ensure they’re readable
  • Helping ensure content is up-to-date
  • Checking for orphaned pages that aren’t usefully connected into the main web of pages
  • Breaking up long pages into smaller more manageable and useful chunks
  • Identifying useful content to be contributed
  • Promoting the wiki within their own department or team
  • Renaming pages to better reflect their contents.

Ideally, your wiki gardeners will emerge naturally, but you can actively recruit them from individual departments. The idea isn’t to delegate maintaining the wiki to a small team of users; it’s more about community building. It’s essential for the user community to take ownership for their own content, and, most importantly, for other people’s content. This is one important difference between a wiki and traditional groupware.

Naming is everything

Naming is important in a wiki. Try to encourage good naming or navigation will suffer. Page names should reflect their content. Avoid use of abbreviations, acronyms, etc. Wikis work very well with CamelCaseNamesLikeThis. All wiki installations will automatically generate links from CamelCase words to the appropriately named page in the wiki.

With good naming you can write sentences like the following, and they will not only be readable, but also magically gain links to the relevant documentation:

When ConfiguringTheServer don’t forget to DeployTheWidget; if you need a reference read HowToStartTheApplication.

Or, perhaps:

We’re maintaining a list of CurrentClients and CurrentCompetitors. Delivery dates for ForthcomingProducts can be found in the ReleaseSchedule.

Naming conventions are also a good way to indicate that pages are related in some way. For example we often use a project’s name as a prefix for pages, e.g. ProjectNameOverview and ProjectNameReleases, or for user specific pages: LeighDoddsCalendar.

Avoiding a wiki explosion

If your wiki starts to become successful and other departments or teams embrace it, you may find yourself faced with a request that users need a wiki for their department only. Just say no!

If you create many small wikis then you inevitably recreate the kind of content silos that you’re undoubtedly trying to replace. Provide guidance on how users can create pages targeted for their own department, perhaps adopting a naming convention as outlined above. Explain that this will be less effective than a single inter-linked knowledge base. For example the content will not be cross-searchable.

Wherever we’ve deployed smaller per-department or per-team wikis they’ve rapidly grown stale. Either because there wasn’t enough content, or that users were already contributing to another wiki and naturally continued to add content there. In almost all cases we’ve ended up shutting them down.

The only occasion I’ve found when a separate wiki is not only useful but essential is when it’s shared with people outside the firewall. We’ve used a wiki at Ingenta as a way to share documentation with clients. It wouldn’t be appropriate for clients to have access to our main corporate wiki, so a separate installation works better.

Within an organisation, ensuring people share information requires extra work – anywhere from 30 minutes to a whole day. But I know I’m not the only one keeping an interested eye on the RecentChanges page on our wiki to see what’s happening elsewhere in the company.

Hopefully this article has provided some useful pointers that will help you explore the potential of your own corporate wiki. I’ve found it fascinating to see how a wiki environment can facilitate sharing and contribution amongst teams, as well as providing a low-cost and simple way of capturing knowledge within an organisation.

Embracing the Wiki Way

I was recently invited to write an article for the FreePint newsletter. The article “Embracing the Wiki Way: Deploying a Corporate Wiki” is now available. It serves as an update to my blog entry on bootstrapping a corporate wiki with more of an emphasis on tips for users.
If you’re thinking about deploying a corporate wiki then hopefully the article may help you plan your strategy. There are also plenty more case studies available for you to compare with.

Benefits of Refactoring to REST

Edd sent me a pointer to a nice article from Scott Raymond called “Refactoring to REST” in which he outlines how his application code was improved and simplified by adopting a more RESTful design. The application here was built on Rails and used the Simply Restful plugin to nudge Rails into a more RESTful aspect.
I’ve noticed a similar reduction in complexity when moving to RESTful application design. I’ve tended to describe this as reducing the “surface area” of the application: the smaller the surface area, the less code is required. It also follows that the smaller the surface area, the less URL types are required. You end up with fewer fairly standard URL patterns which identify resources, rather than RPC-style “method” oriented URLs.
This has some nice properties. For the client a given server application becomes more easily substitutable, as there’s less coupling. And on the server side it clarifies the “points of contact” of the application with the web (of data). It also makes it easier to maintain permanent links because as the URLs are simpler and more identifiable they’re easier to rewrite/redirect as an application evolves or changes architecture.

Follow

Get every new post delivered to your Inbox.

Join 30 other followers