June 14, 2011

Chapter 10 – Written Communication

Wiki is a quick and easy system for creating, linking, and categorizing reference documents. It is available to everyone, editable by everyone, and tracks the history of changes made to each page. Wiki is a freeform structure; you and your team can fill it up any way you want. This flexibility is the greatest strength and the greatest weakness of wiki.

Wiki systems are well suited to documents and document-style information. They are a good place to share design documents, procedural documents, and meeting notes. When a new member joins your team you should be able to point them to your team wiki as the first place to look for information.

Wikis need naming conventions

With a forum or a mailing list the subject line of each post can be more relaxed because they are stored chronologically. Reusing an email subject from a year ago is fine because most people will have forgotten the older email. Naming conventions are key to keeping your wiki manageable because each wiki page is persistent and requires a unique name. Wiki page names must follow a naming convention or they will quickly become impossible to manage.

When your team starts a new wiki you should strongly encourage them to create a naming convention for the wiki pages. A good page naming convention for a wiki should specify the following topics at a minimum:

  • Upper and lower case letters – MyDesign vs. Mydesign vs. mydesign
  • Group names as prefixes – MyGroupMyPage vs. MyGroup_MyPage vs. MyPage
  • Agreed names for common terms – e-mail vs. email
  • Words to avoid – For example, it is generally a good idea to avoid your company name since all the pages are about your company
  • A common language for page names – It is much easier if you choose a language that can be represented using English only characters

Wikis need constant maintenance

When you add a new page you need to think about how it fits in with the rest of the information in the wiki. Make careful choices about where the page should go, what it should be named, and where it should be linked from. Make some plan and stick to it. A bad plan is better than no plan at all.

Sticking with your plan will be a constant effort with your wiki. Some wiki packages provide tools to automatically detect certain issues like orphaned pages, but you and your team will need to continually edit and refine the contents of your wiki or it will become disorganized and useless. A well-planned wiki will be a benefit to your team; a poorly-planned wiki will take a lot of time and effort without giving you much in return.

Previous post:

Next post: