Brendan Burns

As you might have gathered from my last post, over recent years I’ve found a team wiki to be almost indispensable.  I think every software development team should have one!

So what is good to put up on a software development wiki? Overall I think the goal of a team wiki should simply be capture anything useful that the team knows, as far as it is possible and reasonable.  At the very least it should hold details of how to get stuff done, in order to maximise productivity of the team while minimising errors due to inaccurate information

Generally, I have found that “How-To’s” work well, as do checklists, explanations, and any sort of reference information.

In more detail, here is a list of things that I have found useful to have on a software development team wiki:

• Diagrams and explanations of system architecture
• Design considerations/limitations of certain aspects of the system
• Data flow within the system and to/from other systems
• Application-specific business (domain) knowledge
• Coding How-To’s for developers, such as how to add new components to the system
• How to set up environments. For example, how to set up a new development environment, how to set up a new QA box, build machine, etc)
• How the build process works and how to perform different builds
• Pre-release testing procedure, including sanity checks and regression testing
• Release procedure (including pre- and post-release tasks)
• How to perform deployments
• Details of user acceptance testing
• Details of who to contact to get stuff done. eg, “to create a new user account, contact X team at Y email address”
• Checklist of items to be done before new employees arrive
• Details on how to make requests, eg how to request a new machine, how to request different accounts to be created
• Email templates. eg, for requests, or for standard emails to users
• How to solve typical support issues, possibly with links to issues in a support system (eg, jira)
• If working in iterations: how to create a new iteration
• If working in an Agile environment: information on past spikes that have been executed and results achieved
• Project planning information, like goals, milestones
• Ideas for new features
• Ideas on how to improve technical aspects of the system and/or development process
• Details on servers that the team “owns”/accesses
• Information on server-side services that regularly run in the background
• Details of down-stream systems that consume output from the system
• Coding standards

The target audience of such a team wiki can be broad: developers, QA, support, managers, members of other teams.  I have also found it very useful put information for users up on a wiki when working on company internal applications. Users then see the latest information, and can even update it themselves if necessary!

Taking this idea further, why not use the wiki as the source for application help? Help pages are so 1990’s, aren’t they?  With a wiki, any questions or issues that users have can then be documented (and improved) immediately, rather than waiting for the next release.

The goal of including information for users on a wiki is to keep users better informed and reduce load on the team in supplying information to users, thereby improving the team’s productivity.

Some specific items I have found useful to put on the wiki for users:

• In general, anything that can help users use the application more effectively
• How To’s, with screen-shots and walk-throughs
• Results and procedure for user acceptance testing
• Manager/developer contact details
• Release notes
• Meeting minutes
• Discussions of requirements

How about you, have you found any of the above useful to put on a wiki?  Please feel free to add your suggestions.

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:

1. All knowledge in the system should be trivially easy to find, to read and edit.
2. The system needs to be accessible and editable by all members of the team.
3. 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.)
4. Closely following Point 3, the system needs to be reliable.  Any downtime means lost knowledge, lost productivity, and disruption to the knowledge-sharing habit.
5. The system should support linking between different knowledge items, similar to the World Wide Web.
6. 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.