Thu 10 Sep 2009
There’s a great old commercial for Tootsie Roll Tootsie Pops that reminds me a lot of what happens on most software projects. The commercial features a crudely drawn cartoon of a boy trying to figure out a vitally important question.
Boy: Mr. Turtle, how many licks does it take to get to the Tootsie Roll center of a Tootsie Pop?
Mr. Turtle: I’ve never even made it without biting. Ask Mr. Owl.
Boy: Mr. Owl, how many licks does it take to get to the Tootsie Roll center of a Tootsie Pop?
Mr. Owl: Let’s find out. A One… A two-HOO…A three.
(crunch sound effect)
Mr. Owl: Three!
This illustrates two common problems in oral communication. The first is the iterative process of finding someone who might know the answer to your question. In software development, the questions are typically of a more concrete nature, relating to a specific design or implementation choice.
Most software projects depend on a great deal of local knowledge. This is knowledge that is specific to the project, something you couldn’t know prior to working on the project. This include things like architectural and design details. The local knowledge is rarely written down in an organized manner but is contained in the collective experience of the development team. Because it isn’t written down and cataloged it cannot be searched, except through the iterative query process.
The other problem that this commercial illustrates is that of false experts. Like Mr. Owl, you will find people who will give you a definitive answer but one that is, unfortunately, wrong. In software development, it can be very difficult to spot these wrong answers–you don’t get to see someone just bite into the Tootsie Pop to come up with it.
In some cases, the person may truly believe the answer they give, and we’ll assume that until we have proof to the contrary. At other times, people just don’t like to admit that they don’t know something. So, they make up an answer. In either case, the damage to your work is just as bad.
Folklore is typified by this kind of oral communication. It is the main method for communicating important information in primitive cultures. Knowledge is passed from one person to another. Often, because of miscommunication, the knowledge is corrupted by each successive telling.
It’s like that party game where you start off with a sentence and have each person whisper it to another person. This is repeated several times and then the last person writes down the sentence. In the end, the meaning of the sentence is often radically changed with comical results. The same thing happens in software development, but the results are far less comical.
The solution to both of these problems is to document local knowledge. One form of that is code comments. So much has been written on that topic, that I don’t feel the need to add more. However, many things are not appropriate to store in code comments. It’s that kind of knowledge that is most often passed along as folklore.
Fortunately, technology has given us a solution. A wiki provides a centralized knowledge repository that is edited by the group. This allows for the information to be easily reviewed for accuracy. It also eliminates the need to wander around and find someone who might know the answer to your question.
It also addresses another problem. Many people are hesitant to go ask questions. Either they are afraid of looking stupid, or they don’t want to trouble their coworkers. So, they will often flounder around trying to figure it out on their own, wasting time, or they will try to make due without the answer. A wiki allows people to find an answer without the potential embarrassment of exposing their ignorance.
To be successful, a wiki needs to be searchable and browseable. The search capability is needed to find the answer to specific questions. Browseability allows someone to view a set of topics and delve deeper to get more information. This is important to allow someone to gain the initial knowledge on a topic, particularly for getting new team members up to speed. Most packages do a good job providing the search capability. But very few provide a good mechanism to build a browseable knowledge structure.
At SlickEdit, we use MediaWiki for our shared knowledge. It provides both an excellent search and a convenient means to organize topics. The side menu allows you to structure your top-level categories, and each page automatically includes a table of contents if it contains 4 or more subsections. This makes it simple to build a logical knowledge decomposition. It’s this capability to create a browseable structure that sets MediaWiki apart from other wiki software we tried.
Finding the right wiki software and setting up an initial structure is only the first step, though. The main challenge is getting the team to populate it. You face a couple of common problems here.
The first is the normal reluctance of programmers to document things. Many programmers despise any activity that is not directly related to producing code. This is a tough nut to crack, since this attitude is often deeply ingrained in the developers psyche. How you overcome this depends on the person and the arguments that they will listen to. You can appeal to their sense of professionalism and explain that this is part of professional development. You can appeal to their sense of teamwork and explain how this helps make the team more effective. You will need your full set of management skills to get everyone contributing.
Even if everyone is willing to contribute, one problem that often prevents a wiki from reaching its true potential is that of obviousness. Once you know something, it seems obvious to you. If it’s obvious, then why document it? This same problem plagues code comments. The best solution is to make the wiki an essential part of the problem solving process. When someone is trying to answer a question, they should look in the wiki. If they don’t find the answer, they should make a note to come back and add this information to the wiki after folklore has delivered an answer.
So, how does having a wiki alter the scenario depicted in the commercial?
Boy: Hmm, I wonder how many licks does it take to get to the Tootsie Roll center of a Tootsie Pop?
(Boy looks in wiki for the answer and finds an entry by Mr. Owl: “How many licks does it take to get to the Tootsie Roll center of a Tootsie Pop? Three.”)
Well, at least he didn’t have to go bother curmudgeonly, old Mr. Turtle.