Somewhere, in a dimly lit classroom, a library bench, or in a home study, some lucky so-and-so is writing an essay from beginning to end with no notes. This splendid individual is able to craft entire sections without forgetting by the end what the section was intended to include at the beginning, and can weave a carefully paced argument with thoughts and references collected over a period of months, all perfectly recollected. Neither of your authors is this person. Instead, we need help, and that help comes in the shape of a wiki.
A wiki is a website where every page can be edited in a web browser, by whomever happens to be reading it. It's so terrifically easy for people to jump in and revise pages that wikis are becoming known as the tool of choice for large, multiple-participant projects. This tutorial is about how to effectively use a wiki to keep notes and share ideas amongst a group of people, and how to organize that wiki to avoid lost thoughts and encourage serendipity.
This article was written using a wiki, as were most of the 100 hacks in our book, Mind Hacks. The prime example of a wiki in action is Wikipedia, the open source encyclopedia. Wikipedia is one of the best resources on the internet, and its quality and breadth lends credence to the wiki as a great tool. But it illustrates just one way of using the wiki.
Wikipedia builds on transparency, simple linking, and a low barrier to entry for crowds of people to be involved in editing and authoring. We can use these same qualities with just two or three people for a different outcome: a shared workspace and, in effect, a shared memory.
As with any large project, we found that a book was too big to hold in mind all at once, and definitely too big to guarantee remembering those many promising ideas that came up at times we were least able to pursue them. Some of these ideas would start as off-the-cuff thoughts and, when followed up, grow to change large parts of our major concept. So it was important to record them, and give them room. A large number of recorded ideas means, of course, that it's easy to get out of sync with project partners, and that's where the wiki as shared memory comes in. Using a wiki for your big projects keeps all participants on the same page.
Before getting into how to choose the right wiki for you and general tips for using one, it may be useful to know how we used a wiki for our own project. Writing Mind Hacks required several different stages of work: First, we had to determine what the hacks would be, and that tended to come out of research on other hacks, or suggestions, or following up on existing ideas. Gathering material came next, and either a story for the hack would be found, or not. Last would come drafting, more drafting, and finally editing.
Something we found happening a lot was this: during research, we'd discover lots of little facts. We'd file these away on pages already devoted to hacks or potential hacks. Later, when we came to write these, we'd find the notes we'd recorded but forgotten, and the writing would be better for it. Often, one of us would make a note, and the other would happen to run across it, and know more about it.
Because the whole book was written on our private wiki, it benefited from these ideas that we could capture without breaking stride--in fact, it was only the easy editing that a wiki provides that allowed us to record these ideas at all. Had it been any harder, we wouldn't have wanted to pause while writing one hack to jot down ideas on another.
But also we benefited because the wiki removed administrative overhead: our meetings were easier because we knew our progress and actions (we had a shared todo.txt). We could confidently post minutes on the wiki because we knew they wouldn't get lost. Our thoughts about the eventual shape of the book were continually on display--and shared--so we didn't have to spend time figuring that out in meetings, either. There's a phrase about wikis: "What you think is what you get." A wiki is a written-down memory with a lot more space than the built-in one, and it's a collective memory, too.
It might seem like choosing the right software depends on what type of project you're planning to use it for, but choosing which wiki to use depends first and foremost on what your web server already supports. We'll give you a couple of starting points on where to find and how to choose which wiki to install, and also what we like.
"Which Open Source Wiki Works For You?" (O'Reilly Network) may be a little dated now (it was written in 2004), but the article is still a great starting point and evaluates wikis based on important criteria. A quick read of this article can give you a good idea of how to choose your wiki.
Wikipedia has a "Comparison of Wiki Software" that includes commercial and hosted software. It's a comprehensive and easy-to-read overview.
WikiMatrix deserves a special mention. It hosts information on a large selection of wiki software, and lets you perform side-by-side comparisons across criteria, from system requirements to markup syntax. This is great when you're finalizing your choice. There's no rating for how easy each engine is to install, however. You'll have to refer to the Wikipedia comparison article for that, and it's advisable to read the installation documentation of the software before you commit to it.
So what should you be looking for? Full disclosure here: we used MoinMoin to write Mind Hacks and were extremely happy with it (it even got a mention in the book). It isn't the only wiki software we've used, but it does stand up very well against the evaluation points below. Installation and upgrading from version to version may present a small degree of difficulty to a beginner with the command line, but should be reasonably simple for those with some familiarity.
Criteria for evaluating which wiki to use:
Something you don't need, necessarily, is wiki software that looks great. Remember, this is about organizing your project, not making pages good enough to print. Some wiki software sacrifice simple syntax for total layout control--don't bother with that.
OK, you've got your wiki up and running and you're staring at that default front page. What now? We'll go into the precise rationale later, but for the moment you can get off to a flying start by following these steps:
Configure it: Lock it down so no one can see it, or just don't tell anyone the address. Next, make yourself a user account on the wiki so you can tell which pages you edited and when. And make sure you subscribe to changes on all pages. If you use RSS, see if there's an RSS feed for "RecentChanges" and add that to your newsreader. If there isn't one, subscribe to emails for all pages. (Hint: If you use MoinMoin and it asks for a regular expression to match page titles, enter ".*".)
Create a starting layout: Break down your current project into self-contained subprojects, and give each a WikiWords-style title. List all these subprojects on one page. We used "AllHacks". You might use "AllTasks". This is the first link you should add to the front page of your new wiki. When you tidy the front page, put all the default text at the bottom (you may need it later) and make a space at the top for your common links and current tasks.
Kick-start those good habits: You want to give yourself every opportunity to use the wiki on a regular basis. Drag links to the front page and RecentChanges into the bookmark bar of your browser. Determine today's tasks (or this week's) for you and your collaborators, and list them on the wiki as "ToDoForJan27" (or whatever). Add that to the front page too, and be sure to add wiki names for each item so you can refer to them later. Finally, set aside ten minutes a day for wiki gardening, but don't specify any particular tasks ahead of time. Grab a coffee then just skim and delete your update emails, and read what you still need to do from the AllTasks list. Follow a few links, and do whatever occurs to you to keep things tidy. After ten minutes, just stop. That's the essence of wiki gardening.
Why might you want to use a wiki for your project? The wiki is:
OK, you get the picture: we like using wikis. But why might you not want to use one?
Given the pros and cons, we'd say your project could use a wiki if there aren't too many of you involved, you don't need to work in public, you're able to do all or most of your work on the wiki (constant exposure is important), and your project is really big.
That said, here are some specific tips when you've decided you're ready to dive into wiki world:
Keep all of your notes on the wiki! Don't make the wiki page too stressful to edit. If you have to write a title, or date, or your initials, or even keep things neat when you make a note--you might not do it. If you have an idea, you want to be able to click Edit, note it at the bottom, and close the window. In this spirit, keep a permanent link to the wiki in your browser toolbar.
Use attachments. Use lots of attachments, uploading PDFs and images when you can, and keep lots of references and links on the wiki. Don't keep any supporting material on your computer.
It's all about getting used to the wiki. Use WikiWords everywhere. We had all of our article titles in WikiTitleCase pretty much until we were forced to give them proper titles. This meant we knew our way around the wiki like the backs of our hands, and could make paper notes that could be easily reconciled with the wiki later.
Don't be uptight about using the wiki for collaboration. Yes, everything should live there, but don't try to work on the same page in the same day or two. You want a good understanding of what's where, and that means nothing changing under your feet. Talk to people to pick up topics. If you're actively working on the same document, break it up into a few pages.
If you need to move off of the wiki to finish what you're working on, that's good too: yes, a wiki is good for collaboration, but it's more important to have a shared memory than a shared workspace. If you need to work off of the wiki--in a Word doc with Track Changes on, or bouncing a text file around in email--do that. Use the wiki when it reduces your workload. You don't need to be strict among a tiny number of people. Wikis happen to be good for collaboration, yes, but what they're really really good for is being a space where it's really fast to write things down and find them again.
Now you're committed to your wiki; here are some tips for staying organized, which will lead to a successful, happy wiki experience:
Keep an index: If the wiki is heavily structured with pages you can only get to with a click-click-and-click-again, you'll never find anything. We kept a single page called "AllHacks," listing all of the hacks and potential hacks. These were organized in the same order as the book, and a note made around each one according to its status. Because they were all on the same page, it was easy to have a quick explore. Remember, you want to be thinking, "Oh, what was that idea again?" and find yourself clicking on the link, reading briefly, and clicking Back without really even noticing. Keep navigation simple.
Keep it messy: Provisionality is key--don't let perfectionism get in the way of throwing down on the wiki all the half-thoughts, potential seeds, links, and factoids that you'll need later.
But not too messy: We talked earlier about "wiki gardening," which is the process of wandering around the wiki tidying as you go. The point isn't necessarily tidying, it's seeing pages and ideas with fresh eyes, too. It's a good habit, it's easy, and really shouldn't just be ten minutes a day--it's continual. Try spending your first cup of coffee in the morning on the wiki, picking up loose ends, trimming the index, and so on. Do more whenever you have a spare few minutes. You'll run across late-night ideas from before that might change your day. Be wary of imposing structure too early, however. You'll find you come to an understanding, as you garden, of what needs to be structured and what doesn't. Reorganization (but not too much) keeps things fresh.
Don't be scared of synonyms: Having lots of pages about the same thing isn't bad if it means you make more notes. But keep all these pages linked off of your table of contents so they can be gardened away later. In fact, it's good to have a lot of text and synonyms on one page because it makes it more likely you'll find it with text search later.
Make context-dependent notes: Keep notes where you think you'll run into them later. This is like sticking the "buy milk" note on the front door where you'll see it as you go out instead of on the fridge where you'll find it just after you boil the kettle for your tea. Or like putting your passport in your shoes so you can't leave without actively picking it up. Dump notes everywhere, but dump notes together on pages with other notes. Remember, the intention is that when you come to actually writing a full article, you run across things you'd forgotten, and can use them to make your article even better.
The wiki is common space for everyone in your group, so here are some suggested house rules to help you get along:
Total immersion: Every edit should be emailed to you, and use the WikiWords in even in private correspondence. We set up our wiki to send an email every time a page was updated (most wikis have a RecentChanges page that you can subscribe to). That may seem like overkill, but it's really not! We could read the wiki subject line and delete the mail. Doing this, just scanning down your inbox gives you good background awareness of what's changing, and where. (If you're an RSS hound, you can subscribe using a web feed instead.)
Comment in situ: Feel free to make comments on everyone else's ideas and writing on the same page--maybe even in the same paragraph. You'll figure out a standard for commenting to each other (use bold, perhaps, or use square brackets and your name). Doing this keeps conversations together and out of the immediate workflow, where they're able to proceed at their own pace without interrupting any urgent work. It's also an incentive to follow the RecentChanges email subscription closer. On these same lines, make sure you log in to the wiki and have a meaningful username. If you don't use this to see who did what, you'll forget.
Don't share too much: Keep the wiki private. Life's too short to have to be aware of what the public are doing to your space. Think about it like a shared office where everything is where you left it and you're used to each other's presence--it'd be annoying to come in one morning and find the books on your shelves alphabeticized when they used to be in easy-access order. Put a password on your wiki.
Be non-precious: Wiki software helps you let go of your own writing and not feel precious about it, and gives you practice at getting thoughts out of your head into words (because the pressure's low). Both of these are essential for a successful collaborative project, and can be hard to learn. Remember: feel free to edit your colleagues' pages, and feel flattered when they help out by editing yours--even when they delete all of your words and totally rewrite it. It can be painful to start with, but it's about the project, not about you.
Be precise: Gardening and ease of editing doesn't mean you should be shoddy or slapdash--for effective sharing, you want your collaborators to know exactly what you mean. Watch your spelling and grammar, be clear, and don't expect anyone to clear up after you. This is true for collaborations in general, but when you're not physically sharing the same space it's more important to be aware of what you're doing.
It's not all about the writing and how to get along. We have a few tips for whoever's responsible for the technical side of the wiki, too:
Always back up: If you're a hacker, consider installing the wiki software
on your laptop and using
rsync to copy it over periodically. You'll have
a local copy for reference, and a backup should the server have any trouble.
Never upgrade: Never upgrade your wiki software halfway through your project, even if you think you need an extra feature. It's too easy to get sidetracked into updating and upgrading. It's not about the wiki, it's about the project.
Pick carefully: The wiki software is a huge factor in whether your everyday work is enjoyable and productive. Remember to check the engine against the evaluation criteria given above, paying particular attention to page histories, user accounts, and attachments. Being able to subscribe to changes by email (or RSS) is a must.
Wikis are at their best when a small number of people are working intensely on related material. They're messy, immediate, and a powerful way of sharing thinking space with your collaborators.
Once you've used a wiki for a project, you'll find it hard to go back to regular methods. You'll find yourself using wiki syntax in emails, and your own WikiWords in conversation. Using the wiki as your notebook will ensure you don't lose the seeds of good ideas, and spending time browsing and gardening will keep those ideas returning when you need them. Most of all, you'll find that having a shared memory on a large project moves the administrivia out of the way and lets you concentrate on the real job.
Tom Stafford has a PhD in Cognitive Neuroscience and is currently a research associate in the Department of Psychology, University of Sheffield. He is also an associate editor of the Psychologist magazine and has previously worked as a freelance writer and researcher for the BBC.
Matt Webb At Schulze & Webb, Matt Webb engineers, designs, and hacks technology and physical things. He is also the coauthor of Mind Hacks, cognitive psychology for a general audience.
Return to the O'Reilly Network.
Copyright © 2009 O'Reilly Media, Inc.