(2012: This post has been edited to remove company-specific information

Over 3 years, we built the best team wiki in the organization and garnered 6 consecutive awards doing it. This post was written 3 months after we began.)

Problems/Learnings

Reluctance

We were asked:

Will using the wiki ensure that documents are updated when the design/code changes?

No, but if someone wants to, he/she will find it easier.

What happens if the wiki goes down?

The data can be regularly backed up.

How will we ensure that the information stays accurate? What if a developer changes information he shouldn’t have?

Our problem so far has been that developers DON’T update information. Also wikis come with very good version control. We can always revert back changes. We can also highlight important information that shouldn’t be experimented on.

So we put this up on the wiki, how do we send this information to clients? Can we export to a doc later?

Yup. Plugins!

and very many more such questions.

Lesson: Be prepared to defend even the obvious choice.

Suitability

The wiki was built for collaboration but is a little hard to get used to and a wiki-page-like feel isn’t what one looks for in product/project documentation.

Security was a concern too. We wanted to use the wiki to program-manage and this meant putting up information not suitable for everyone in the organization to view (personal numbers, contacts).

Solution: we switched from the wiki to Teamwiki. Teamwiki is a little easier to use for the newbie, provides plugins/features that allow the team-admin to customize the team-specific wiki quite significantly and access is restricted to the team.

Time

It is unfortunate but documentation is considered unimportant by most people and enough time is never allotted for this activity. Most of the work on the wiki happened on personal time.

Lesson: Be prepared to work harder to back up your claims (at least in the beginning).

Beginning

Starting with a blank slate caused its own difficulties. One or two experts had to create stubs, bring up main pages, FAQs, presentations that the rest of the team could then emulate (managerial-word for ‘copy-paste’).

NOTE: Here too, the team wiki has some advantages: it allows you to customize the default page creation and add nifty things called Forms. Used together, they ensure that every page is very easy to create and is immediately tagged, indexed and displayed where it needs to be (based on its tags)

Lesson: Will put a little later. Is in my mind but am yet to put it in words.

Participation

A problem we are yet to crack. How do you build wiki-culture into a team? Currently the emphasis has been on making the adoption as easy as possible, but that is not enough.

We’ve got a while to go yet. The experience so far has been encouraging. 3 months into this project, we’ve built more useful information mechanisms than have existed in our product documentation in years. All we need now is for the team to use them…