Using a Wiki for Documentation and Collaborative Authoring
By Michael Angeles
Michael Angeles is an information specialist at Lucent Technologies. He
can be contacted via his home page and weblog at http://urlgreyhot.comPublished November 28, 2004
Introduction
Documentation may help to ensure efficiency, continuity and consistency in library operations. Library technical staff might consider the use of collaborative publishing software for documenting their internal processes and procedures. Wiki software for collaborative web publishing has emerged as one of the viable and inexpensive options to consider for maintaining group documentation. There are many inexpensive or free Wiki packages at our disposal and while they may not necessarily bend to meet our every requirement, with a little work can serve many of our needs.
A Good Fit
I had my first experience using a Wiki for project documentation when I participated in the formation of a professional association. The group was geographically dispersed, and after our first face-to-face meetings, it became clear that we needed a platform to supplement our email meetings and conference calls. We quickly set up a Wiki, and it became everything from the white board to capture our post-meeting ideas to the documentation repository for our initiatives. Wikis proved to provide a lot of publishing functionality to this organization with little financial investment. Since we had limited financial funds as a start up, this seemed the perfect fit for our needs.
Wikis can be both simple and complex. On the surface, the idea of the Wiki is simple and elegant, and conceptually this simplicity makes Wikis a good candidate for modest documentation needs or informal, shared notes capturing. Because they’re hypertext publishing environments, however, they can also become quite sophisticated and complex. This duality is precisely what makes them attractive and compelling tools for documentation.
But when it comes down to it, they’re only effective tools if you invest time and effort in making them work for your particular group of users. I’ve learned from the projects I’ve participated in that the greatest success factors for integrating technology into a business include building an understanding of users and removing the barriers to the use of the technology. The technology itself is really of secondary concern. The solutions that are most successful are often the simplest in execution. Understanding how people work and closely matching the system design is one step towards this type of simplicity.
In the end, whether we choose a Wiki or some other technology, we want our interactions with the finished product and the output it produces to match our understanding of user goals and needs. Keeping this in mind, we are going to take a look at how my organization is learning to utilize our StaffWiki.
Getting Started
My organization began testing a Wiki over a year ago as the platform for some of our internal documentation and collaboration needs. In the short time that we’ve been experimenting with our StaffWiki, the Wiki quickly replaced our previous documentation tool and is presently utilized on a daily basis, whereas the previous website was characterized by a sense of stasis and link rot. But getting the organization to jump in wasn’t easy at first. There were some obstacles to overcome and keeping the Wiki useful requires investing time in managing it.
In most cases, a Wiki is set up so that anyone with access can edit or create new pages. To edit pages, you click a link on the page that reads “Click here to edit this page”. To create new pages, you usually create a WikiWord (also called a CamelCase word) on an existing page by removing spaces between 2 or more words, or you may use a special syntax such as enclosing links in [[double brackets]]. After you save the edited page, you click the question mark next to the WikiWord you typed and the Wiki forwards the browser to a web form for typing the new page contents. This description summarizes how Wikis work, but the reality for most people is that while simple on the surface, getting started still has a learning curve.
It seems like people fall into two camps when they meet Wikis for the first time. Either they fall in love with the use of hypertext on Wikis or they run away screaming. That is a generalization of course. Truth is, like many people I’ve encountered, I had a hard time at first understanding how to find things or figure out how to contribute to a Wiki. Some of the difficulty had to do with understanding the scope of the Wiki and figuring out how to explore and navigate. Wikis are often loosely organized. This means that hierarchy doesn’t necessarily organize things and the path to a nugget or node within a Wiki may not be apparent on the home page. For information workers used to order and clearly outlined organization, that makes Wikis a findability nightmare. But once the organizationally fussy and Wiki-timid newbies like myself started to see how easy it was to add our opinions to these pages, we saw the light. Soon after, we realized that we could contribute new pages to the community and we got hooked on the idea of the publicly editable web page.
Getting people comfortable with “clicking to edit” pages is usually the first hump to get over. In our experience, that has not been the biggest obstacle to getting our Wiki used. Getting people to publish new pages, however, has required a bit more help and instruction.
To start our StaffWiki, I began by creating an outline of the categories of information we had on our old manually maintained Staff site. Our main categories are: Communications, Organization Information, Resources and Documentation, External Resources. Within these major categories we list pages that we create on the Wiki including project pages that list our meeting notes, documentation and deliverables. Creating this outline for the Wiki made it much easier for people to see where to start.
After our initial outline was in place on the home page, I then ported our static pages from the old site to the Wiki. Giving the staff something to react to rather than providing them with a blank slate for them to fill was necessary to encourage them to start using it. The idea was to present it as something familiar at first – web pages that they can browse through and read – and then demonstrate its usefulness for collaborative publishing later. I thought that proving the concept by using it myself would be more effective than evangelizing it. I started by posting commonly referenced information including the following:
Organizational information — our mission statement, marketing materials, links to group calendars
Communications information – past formal communications to staff, links to email list archives
Common files — licensed software we use, forms and template
Logistical information — network printer IP addresses
Group documentation — tutorials, process documentation I held informal training sessions within my department to get people comfortable with the idea of creating and editing pages on their own. Slowly, the process of emailing me to update the old website began to whither away as I answered requests by reminding people of the “Click here to edit” functionality and giving step-by-step instructions if they chose to update the page themselves. Usually I would say, “Thanks, I’ll update the page. Remember, that if you need to make further changes later, you can also update it whenever you need to by just clicking the ‘Edit this page’ link on the bottom of the screen.”
With some time, my department slowly began to edit and add new pages on their own, starting with updating the essential worklife-related information we use occasionally and moving on to creating new pages to document project-related work. Eventually people outside my department started participating, but the majority of active authors is still small. Perhaps 1/4 of the staff are regular updaters. Some people prefer to channel changes through a few selected gatekeepers.
Getting organized Keeping pages organized might be the next major obstacle to familiarizing people with your Wiki. The organic growth of a Wiki can make findability difficult for people accustomed to hierarchical browsing and not using Search. Creating categories for the pages and keeping them organized in a hierarchical list on the home page may help to make them more easily findable and may therefore greatly impact Wiki use.
One of the roles of your Wiki administrator may be to have someone watch the “Recently updated pages” to find the new pages that appear and link to them on a category page or the home page. People will be able to create new pages anywhere on the site. They can also refer to other pages just by typing the name of a page using WikiWord format. For instance, I have a Wiki page for our library portal documenation. The page is called “InfoView”. This means that anytime someone types the term InfoView into a Wiki page, that term is linked over to the InfoView page.
As you can see, although a Wiki page is usually created from another page, that page doesn’t necessarily serve as it’s sole parent. In the example above, every reference to InfoView creates a link between the pages, but that doesn’t mean that they’re really related as parent and child, so to speak. For the home page outline, I usually end up keeping the overview of the Wiki somewhat high-level and let these more subtle relationships be uncovered as you explore the sub-pages a bit more. But when I notice an important new page or a page that should serve as a new rubric, I surface it on the home page to emphasize our high-level categorization.
Once someone links to that page, the page is hypertextually related to it. So a page called MyPage that is linked from several other pages is related to all of them. This is true of all poly-hierarchical site organizations where a page falls under many parents. The trouble is, that for many users, the hierarchically organized sites look easy to understand on the surface, while the hypertext Wiki looks like a constantly growing, many tentacled hydra. To keep your Wiki under control you may need to create categories. Watch the growth of recently updated pages and try to assign pages to categories manually.
If you trust that your users will help a little to keep things organized, you may also try this trick. One of the unique things a Wiki does is allow you to see other pages that cite the page you are viewing. This is called a “backlink”. Think of it as a reverse-citation. Usually you click the title of the page or a link that reads “Backlinks” and you are shown the citing pages. Backlinks are sometimes used to manage categories by linking up to a Category index. To do this, create a page on your Wiki for holding categories, e.g. SiteCategories. On every page that you view as a main category for the site, insert a link to the SiteCategories page. It’s useful to put this in the bottom of the page, for example. Then when you navigate to the SiteCategories page, view it’s backlinks to see which pages cite it. It’s a little complicated, but it’s a hack that works.
Documenting projects
When we began to document our project related work, the value of the Wiki became more evident. Long ago, we began to create email discussion groups to archive and document the decisions we made by email. But decisions made in meetings and hallway conversations got lost. When we had to go back and recall why we made certain decisions, if they weren’t formally documented in requirements or discussed on email discussion groups, we sometimes had to guess at our logic or recreate the conversations.
We continue to utilize email discussion groups to archive email conversations, and the Wiki serves as nice place to organize, outline and record thoughts that are hashed out in meetings and email discussions. Increasingly we are also using the Wiki to manage projects. In our project pages, you might typically find these types of information:
Meeting notes
Product specifications gathering notes
Product requirements documentation
Project deliverables, e.g. wireframes, content audits, etc.
Technical documentation Style guides This is typical of the types of information we’re adding presently. We are still using traditional software for producing most of our documents (e.g. MS Word, Excel, Visio) and simply posting links to them. The organization of this information via the Wiki has made it easier to quickly post new information, annotate it and find it later. This is why we’re growing to use the Wiki more every day. They are by no means seen as a replacement for the tools we use during our normal processes that are best suited to document creation, but they are enhancing communication and information organization by giving us a to for supplementing our processes and also serves as our organizational memory.
Sustaining growth
While it may be easy to get a Wiki up and running, the real test of a Wiki’s value will be its ability to be continuously utilized. Below are some best practices that may help ensure the sustainability of your Wiki.
Train your users — Hold informal training sessions at the beginning of your project and make yourself available to help users on an ongoing basis
Keep it organized — Invest time in creating and maintaining category pages, and when you see uncategorized pages, talk to the author about putting them in a category
Understand use — Watch the recent changes page to understand how people are using the Wiki
Lead by example – Use the wiki in all of your project work and to document commonly used staff resources, processes and procedures
Protect — Public Wikis may be open to edit-spam, so protect yours and back it up often Style guides Observations of our progress
Library Staff have reported that the Wiki has worked very well so far as the solution for our self-publishing and collaboration problems. I am still surprised and pleased whenever I hear or read the term StaffWiki used in every day conversation and in emails with my colleagues. It has permeated our organization. Beyond the technical features that make the Wiki simple to use, there are other factors at play here that have made the Wiki so successful.
I’ve found that one of the elements that makes Wikis useful is that they bring back an aspect of knowledge work that we started missing when we stopped passing papers from person to person and annotated them. Malcolm Gladwell talks about the loss of the knowledge creation process in his New Yorker article, The Social Life of Paper. Gone with web pages are the visible comments, scribbles and modifications. On a Wiki, we simply add or annotate as we go and the revision history is saved for us to review at a later date. In a sense because Wikis allow us to view page history and allow us to add notes to pages within the context of particular words or sentences on the page, they bring back some of that visible collaboration that took place on the paper document. This is an important characteristic for community-authored documentation.
Perhaps what makes Wikis most compelling is both their democratic nature and their ability to capture the knowledge of those that contribute. A Wiki provides web authoring to the masses. It takes advantage of the flexibility of hypertext to create open, collaborative spaces for group authoring and editing of information. In open Wikis, you’re not barred from having your say, though you may be edited after the fact on some Wikis if you’re off-topic or offensive.
We’ve seen successful Wikis that have been used for large collaboratively authored bodies of information ranging from the Wikipedia, a Wiki-based encyclopedia, to smaller subject-specific knowledge repositories such as the Knowledge Management Wiki. What makes Wikis such as these so valuable is that the organic growth of their communal knowledge is recorded and visible and serves not only as document archive, but also as the communal memory of all who have participated. This, I think, is my reach goal for our StaffWiki. If we begin to look at it as a tool for more than just publishing logistical information and facts, and perhaps also for capturing and sharing some subject-area knowledge or expertise it may become even more useful to the organization.
Summary
Wikis can be an open, flexible platform for collaborative web page authoring. They reduce steps in workflow and work very well in small, controlled groups. But as with most projects that will depend on user contribution, its success depends on ensuring that you make the system bend to meet the processes and needs of your users and that you are able to invest time in training and in continually managing it.
