Wiki Tips: Joining an Existing Wiki

It can be disorienting to start contributing to a wiki for the first time, especially if you have used email and document repositories for all your previous electronic collaboration. Here are some tips to help you get started.

1. Find the local landmarks

A wiki server does not provide any intrinsic structure for organizing collections of pages. Teams find different ways to create their own structure. Some wiki software allows pages to be arranged into hierarchical trees, which may not be obvious from the default user interface configuration. You may need to configure your settings to show the hierarchical relationships between pages, or select a specific link to see a tree view the pages. Here's how you do that for Confluence:

• http://confluence.atlassian.com/display/CONF20/Tree+View+of+Pages

Even if the software supports page hierarchies, some teams may prefer to use a flat structure with a web of links between pages. If that's the case, find the pages that serve as hubs and main entry points. For example, here are two entry points to the original wiki server:

• http://c2.com/cgi/wiki?WelcomeVisitors
• http://c2.com/cgi/wiki?ExtremeProgrammingRoadmap

2. Create pages by linking to them

Here's a time-saver for creating a new page with a link from an existing page. Edit the existing page, add a link to the new page (which doesn't exist yet), and save your modification. Click on a link to a non-existent page, and you should get the page editor with the page's title filled in.

This is also useful for creating an initial outline, leaving the actual pages to be created later.

3. Publish drafts early

"The best reason for putting anything down on paper is that one may then change it." - Bernard De Voto

The wiki and its pages are the most recent draft of a living document, always open for rewriting.

Add content as soon as you have enough material to create an incomplete rough draft or even an outline. Leave markers where you plan to add more information or exposition. Other people will sometimes fill in the missing text, but don't rely on it - you might be disappointed. More importantly, early drafts provide clues about how you are thinking. Your team members may be able to share insights that save you time or open up interesting new possibilities.

4. Sign comments, not content

Writing for a wiki should be in the style of a document, rather than a conversation. (This doesn't apply if you are writing in the form of a dialogue for pedagogical or dramatic reasons!) When inserting comments into the middle of a page, like attaching sticky notes to a paper document, feel free to sign your name. If you have comments at the beginning or end of a page, like notes in the margin, it may also be appropriate to leave your name. That tells your collaborators who to talk to about the comments. However, it is probably best to have that discussion on a mailing list visible to the whole group. In that case, it doesn't really matter if the comment is signed. Resist the urge to put your thumbprint on a piece of content that says "I wrote this!". That clashes with the collaborative spirit of a wiki.

5. Trust the history features

You might be tempted to leave old content in a page, even if it's no longer valid. That's usually a bad idea, especially if it leaves multiple versions of the same text on the same page. If information is obsolete, update it or remove it. You can explain your changes to the team in an email, or possibly in a revision message that the wiki stores in its history.

If people reading the wiki page need to know that some information is no longer valid, then document that on the wiki page.

Most wiki software allows you to view old versions of a page, view the dates and authors of previous changes, and view the differences between two versions. Use those features to look at a document's history, and keep the latest version of the document clean.

6. Put everything in the wiki (unless you have a better place for it)

Capturing information is the first step toward sharing it. If you don't already have a system designed for storing some type of information, put it into your wiki. Most wiki software allows files to be attached to wiki pages, so you don't necessarily need to have a separate document repository. The goal here is to make all information available to the whole team. Don't hoard it on your private email files or local disk drive.

7. Learn to export

If you want to freeze a version of some wiki content, export the pages to PDF or static HTML pages. Your wiki server probably provides some export capability. If not, you can use your web browser or some other tool to download the web pages for safe keeping.

This is also useful for sharing private wiki pages with people who can not access the wiki directly.

8. Watch for recent changes

Good wiki software allows you to subscribe to email notifications for an entire wiki or individual pages. Register for notifications of any area of the wiki that you are working with. You may also want to subscribe to RSS feeds, but only do that if you will actually read them as part of your normal routine.

9. Try editing "raw markup"

After you have become comfortable editing wiki pages with the rich WYSIWYG editors, try editing the raw "markup" text. Wikis traditionally provide a simple notation using plain text to represent formatting. For example, placing asterisks (*) around a word may cause it to appear in a bold font. You may find that it makes creating complex wiki pages faster and easier. Or you may hate it. Still, it's worth a try.

Some wiki software only provides this type of raw "markup" for formatting. If that's the case, you are likely to hate it at first. Give it time. It could grow on you. If not, lobby to upgrade to more modern wiki software. MediaWiki is one of the few popular wiki servers that doesn't offer WYSIWYG editing by default, but even that has a plug-in that can add rich editing from within a browser.

10. Know when to pick up the phone

And lastly, some common sense. If the collaboration is stuck, or if there are conflicting opinions that can not be resolved through comments in the wiki pages, then resolve the situation by communicating directly with your fellow authors. Have a conversation in person, if you are in the same location. Otherwise, you have several options for communicating: email, instant messages, and the telephone. A wiki can be great for collaboration, but it's not always the most effective tool for communication.