Do you have a wiki?
When joining a new development team, one of the first questions I usually ask, right after “where is the coffee machine?”, is: “do you have a wiki?”. I have used wikis in software development environments over the past four years and I now think of a wiki as one of my core tools. I’m so enthused on them that at one stage I had “wiki evangelist” written somewhere on my CV. (… then I realised that it sounded a bit silly so I took it out).
In this post, I’m going to talk about the importance of knowledge management (KM) in software development and why I think wiki’s are such a good solution as a knowledge management system (KMS).
The importance of knowledge management in software development
Knowledge management has been defined as: “The capabilities by which communities within an organisation capture the knowledge that is critical to them, constantly improve it, and make it available in the most effective manner to those people who need it, so that they can exploit it creatively to add value as a normal part of their work” (Royal Dutch/Shell as reported in BSI, PAS 2001) .
Hmmm, “capture the knowledge” one might ask… isn’t that just documentation with a fancy name? And what is the use of software documentation these days anyway; aren’t we beyond the days of document-heavy software development? Isn’t it best just to speak to people and look at the code to find out how the system works…?
This is all true to a degree, but I think we can do better. The full software development lifecyle really is quite broad and encompasses a lot of different knowledge-based activities, including planning, ideas, specifications, system architecture, environments, disaster recovery, knowing who to contact, answers to typical support questions, release procedure… and much more. All of this information is system knowledge, and it should all be communicated as efficiently and accurately as possible between members of the team at the moment it is needed, and possibly with other teams too.
Another important reason for KM is the fallibility of the human brain. I wish could tell you how much we forget within a week of learning it, but alas, I seem to have forgotten the statistic… any useful knowledge should be written down to ensure accurate retrieval at a later stage. (If, like me, you have struggled through a “how-to” article with a missing/incorrect step you will know that inaccurate information can mean hours of pulling of hair!)
KM is also equally important to small teams as it is to large. In small teams, turnover tends to be lower, but the impact is much higher when a person does leave as the percentage of knowledge leaked is generally much higher. In large teams, the system is often much bigger and turnover tends to be a factor, so getting new developers up to speed as quickly as possible can often become an issue.
In conclusion, KM is very important to personal and team productivity. If you don’t have first-class KM then your team may either be working at non-optimal productivity and/or your team is at risk of knowledge leak if a key team member were to leave the company.
So, what should a successful KMS look like?
Key characteristics of a successful knowledge management system
To be truly successful, I believe the following criteria should be satisfied, to maximise the effectiveness of the system and for team members to “buy in” to it:
- All knowledge in the system should be trivially easy to find, to read and edit.
- The system needs to be accessible and editable by all members of the team.
- The system should be universally accessible from any different machine/device. (Since knowledge may be required and gained at any point in time, the knowledge management system should also always be accessible.)
- Closely following Point 3, the system needs to be reliable. Any downtime means lost knowledge, lost productivity, and disruption to the knowledge-sharing habit.
- The system should support linking between different knowledge items, similar to the World Wide Web.
- Version management should be automatically be handled such that the most-up-to-date information is always presented.
Why I think a wiki is such a great knowledge management system
A wiki satisfies the above criteria by
- allowing the team to collaboratively edit information using a very simple and easy to learn interface, which is accessible via the ubiquitous browser. The barrier to entry of writing documentation is thus set very low, particularly for people with good IT skills.
- providing indexed database-based searching such that information can normally be found within seconds.
- acting as a one-stop knowledge repository, such that only a single piece of knowledge (the wiki URL) is needed to access it.
- being highly reliable: you only need to look as far as Wikipedia to see that they are a proven product (the software that Wikipedia runs on also happens to be free).
- supporting easy linking via hyperlinks to other pages in the wiki, or externally
- handling versioning naturally, such that the version presented to a viewer is always the latest version. The history of any page can still be accessed if necessary.
Common alternatives to a wiki for knowledge management
Now that I have waxed lyrical about wikis, I should contrast some of the common alternatives for knowledge management I have seen in practice.
In my experience, the most common system of KM is a file-based system, often in the form of a collection of Word and Visio documents, stored in some sort of rough file structure, or perhaps buried in an email system, or even stored on individual developers’ machines. I’m sure we’ve all worked in environments with file structures that spread out like a Christmas tree, with documents deeply nested by project, or in a special “documents” folder. Folder and file naming conventions (and even file formats!) can differ from person to person, machine to machine and year to year. Nobody is ever brave enough to restructure the document hierarchy, so it tends to sprawl.
Such a system can start off smoothly, but a major problem with such file-based systems that over time information often becomes difficult to find and edit, especially as the system grows and as staff members come and go. Searching can be slow and frustrating. If the information cannot be found within seconds it’s less likely to be used and even less likely to be kept up to date, thus becoming a viscious circle. Files also introduce the problem of versioning, especially when different versions are stored in people’s inboxes. File-based systems also tend to not be as good at facilitating linking of information/documents. In addition, due to security restrictions, some documents that could be shared are often not accessible by all members of the team or by different teams.
Another common method of KM is to have information stored in developer’s heads, and/or simply in the code itself, with the thinking being that the code always contains the most up-to-date of how the system works, and that developers know the code best. Such a system can function in an open environment (perhaps with pair programming to share knowledge)… for a while. It certainly doesn’t scale very well: it doesn’t help newcomers to the team benefit as much as possible from the team’s accumulated knowledge about the system. It also creates a dependency and bottleneck upon knowledgeable members of the team. It also doesn’t help to mitigate the risk of a key team member walking out the door with large amounts of accumulated knowledge in their heads.
Finally, one other type of KMS for software development is a requirement/issue tracking system. Such a system is indispensable for tracking individual items of work and for getting a snapshot of work that has been done and work to be done. However, they are poor for keeping track of the random pieces of knowledge that one tends to accumulate over time that are not associated with any particular issue, and they are also poor for sharing that knowledge in a way that can easily be disseminated.
There are also some commercial KMS’s out there, but I have no experience with them. If anybody has, please feel free to comment.
Conclusion
I hope I have conveyed how important KM is to the software development process, and why wikis can be an excellent solution for it. In future blog entries I plan to be a bit more practical and give examples of what (and what not) to put on a software development wiki, and how to get team “buy-in” for the wiki.
I welcome your comments, especially if you have any experiences or questions about KM in software development and/or working with wikis in such environments.