What lessons have you learned about using a wiki as a development tool?

Question

I'd asked a question a while back about ways to encourage my team to collaborate. The tool we use is a wiki. Since this is the first time we are using the wiki (formally and as a team), we are learning by committing mistakes.

One of the lessons has been that a wiki isn't suitable for tracking activities. It is better to use a tool built for-the-job (will elaborate if necessary).

Are there other such anti-patterns? What development tasks would you NOT recommend using a wiki for (even though it may seem suitable at first glance)?

Edit: Making this a community-wiki since it is probably unlikely that there will be 'one' right answer.

Answer 1

First-person shooter.

Answer 2

Discussions. While they can be good for recording logs of discussions, they can be problematic when holding an active discussion on a singular page. Talk pages, less so but still troublesome.

I tend to think of wikis as an archive - of discussions, documentation and other related media. A good aim (if your project includes documentation) I think is to write in there things that might be needed in the documentation later.

Answer 3

To write requirements for Software. Simple text document is better. Reason is simple, Wiki is harder to print and text document can be in the CMS when Wiki can't. And, text document can be worked by more people (in the airplane, etc...).

Answer 4

Wiki is suitable for procedure and support. I log every problem i may encounter in wiki so if somebody got the same problem, or if i'm away this day, another person know what to do.

if wiki host all the procedures of the IT department, it is good since all is centralized and you can search them by keyword and so on.

Answer 5

IMHO, a wiki application is good in software shops for writing developer documentation. By that, I mean living documentation, outside of the code, that developers new to an application can read to accelerate their understanding of it. Be advised that this goes against the principals of Agile software development.

If you are going to use a wiki for developer documentation, then I recommend one that authenticates and maintains a revision history. Also, why not deploy a wiki that also bundles a CMS, tasks, and a tracking system for logging defects, etc? If that is the route that you want to go, then I recommend GForge (an OSS solution) and SFEE (not OSS).

It sounds like what you are really more interested in is documenting development rather than developer documentation. The latter has a long shelf life, must be maintained and updated over time, and is used to bring recent hires up to speed quickly. The former helps management strategize and prioritize what should go into the next release. It is also good at making sure there are no ugly surprises when the product ships. If that is more your interest, then may I recommend my own offering called Code Roller?

Answer 6

We have an extensive wiki with everything from requirements to operations procedures. It's very difficult to find anything. There have been several different structures used for organizing the content, limited tagging, and the search feature in the software we use (Atlassian Confluence) is rudimentary.

As a result, there's a lot of valuable information in the wiki, but no one can find it.

Answer 7

Here's a wiki of wiki patterns and anti-patterns that you might find useful: wikipatterns.com

Answer 8

Naming is important.

A good way to dodge this bullet is to start hierarchical sections or categories early, so you don't get a random-pages-farm. While categories are good, they're also best applied "across" to note things that need some kind of attention. Organising into hierarchies like /InternalProjects (an index page) and /InternalProjects/KnightKitten, [...] really helps keep order.

Being comfortable.

It's important to make the wiki your own. It might have authoritative sections that are stricter, but it should have some kind of notes page for each user. If you're new to using wikis, err on the side of verbosity. Wiki writing is an excellent "my brain is spent for the day"-activity.

If in doubt, write!

Write it while you still remember all of it, edit later. No matter how clever you think you might be later, there's no substitute for just vomiting it out in random order now.

• because of the time span between now and later,
• 'cos later might not happen
• 'cos the best way to divide and conquer the job is to remember now, make sense later.

Automatic updating works.

Nobody wants you to sit in copy-paste tedium, least of all your employer. I wrote a tool, WikiUp, to update the technical parts of a wiki, leaving the surrounding discussions intact. It it worked quite well, both technically and socially.