Of many questions you could ask a developers’ team, this one is almost guaranteed to yield an empty face of your interlocutor:

- How do you go about preserving team knowledge and communicating it to all involved team members?

Silence.

- Oh well, we write documentation… now and then… we put some comments in the code where appropriate. We have nice people in the team who answer questions and help newbies when they require assistance.

- Do you think this is an effective strategy?

- Well, it has worked for us. New people come to the team, learn on the job and finally find their way around the project.

- Fine, where do you see a potential for improvement? How would you make the process more efficient?

- Well, now that you ask, we haven't really thought about it…

I bet you haven't.

Sadly, this is what the things are like in many teams around there if not in most of them. Accumulation of project knowledge and experience, its preservation and sharing just happens in the ad-hoc manner. Sometimes it works well, sometimes it doesn't. Sometimes information gets lost, sometimes it gets wrongfully communicated, sometimes the knowledge is present but whoever needs it has no way of knowing if it exists and where to look for it. And still, things are not changing.

Look at how it works most of the time. There is a project with a few years on its shoulders. There is a team of programmers who's been developing and maintaining it. Sometimes there is a core of seasoned developers who know all ins and outs of the project. They are helped by regularly changing new faces who join the project then leave. Sometimes there is a complete rotation of team members in place.

What happens when a new person arrives? Right, it gets tutored on the project. Well, kind of. The poor guy gets thrown at a giant code base and attempts to find his way around it. He reads the code. He follows the comments if they exist. Very often he can't make things out without following some workflow with a debugger down to the deepest level of the project structure to be able to find out what exactly happens down there, what code portion doing what and how it all comes together to implement some function. If he's lucky, there is a helping hand, a nice colleague who'll mentor him and assist him in his fight with this monster. But quite often, there is no such individual or everyone is terribly busy to get distracted with helping the newbie. So he's on his own.

Do you think it is an effective way to introduce new people into a project?

I'll answer that. It is a terrible approach to communicating knowledge.

First, it is extremely inefficient. It takes many months to years to get fluent in a project when approached like this. It doesn’t provide a complete picture of the things, their interconnections, roles and overall operation. It is also extremely depressing. Programmers are very pragmatic people, they like being efficient. They like doing things efficiently. Learning a framework by reading through its source code and debugging it to answer even basic questions is very inefficient. This kind of activities frustrates programmers to no end.

Why then nobody thinks about consolidating project knowledge and experience and putting it into some form that reaches every team member and facilitates information sharing and exchange?

No, it's not again a question about why nobody writes documentation. Documentation is good but it can only take you so far. There is more to documenting knowledge than just commenting every class and method and generating help files out of them. And this knowledge often only exists in the minds of project participants.

Recalling back to my university times, I still keep a very vivid picture of one scene during a lecture. The lector took a brief pause for an off-topic issue of the books we needed for this subject. Turned out some matters were not addressed in the modern books and there were none she could recommend to us on this subject at all. She got a little bit angry seeing she had to give us the needed information personally and verbally. So she commented the state of affairs and said something along the lines of preservation of knowledge only in minds of people and only communicating it through personal contact being a distinct characteristic of older ages while the modern society should have surpassed this organization a long ago.

Sadly as it is, she was right. And looks like this medieval approach is still in wide use.

Let me ask you a question. How did you learn the programming languages, libraries and frameworks that you use in your practice?

Did you get your hands on that framework source code base? Did you dig through it to understand how it works and what features does it have to offer to you? Or did you read a book that presented you with the structured information, code examples and typical usage scenarios?

When you learned a programming language, did you investigate the compiler implementation? Did you read the language specification? Or did you read a structured introduction explaining language features, possibilities and limitations? Along with the code examples, of course.

When you had issues with some tool or a library, did you debug its source code to find out how to use it correctly? Or did you rather ask for help in professional communities on forums, questions and answers sites and followed certain blogs?

Right, there is a large ecosystem for all major tools and products. It starts with the official documentation, accompanied by tons of books and tutorials and supported by a large community sharing knowledge all around. And it works wonderfully.

And it works without personal presence of the developers of those frameworks in your office. You learn to deal with the project without even its source code. In fact, for a good product, you rarely need to get to its source code, though it happens and may be beneficial at times.

Why don't you take then this good example and adopt it in your small team?

It doesn't take to write a thousand-page-book and organize internal developer conferences. Even a few manuals, guidelines and tutorials would do a great service already. If you were to organize all your notes and documents, structure them and keep them in one place, you would do yourself a great service.

Let me suggest a few ideas of what could easily be done and what would bring a major improvement.

Write explanatory comments in code

I don't mean to comment every single class, method, parameter etc. Their general purpose should be obvious from their naming, location, parameter dependencies etc. What you can and should do is to comment every not obvious code portion and explain what makes it tick. Indicate what dependencies it has, what settings might be required somewhere else in code for it to work, what effects on what other function it could have. Summarize the essence in a few words so that a developer could immediately know what he's dealing with.

Writing before about best programming practices, I presented a few ideas which are quite relevant to our present discussion. Writing self-explanatory code (№ 10) and avoiding sophisticated code (№ 11) is by far the best approach to creating the understandable and maintainable code base. Also try to design your code structure in that way that avoids any hidden dependencies (№ 16). In case this is not possible or not desirable (for performance reasons, for example), this is one case where you have to write a good explanatory comment to mention such dependencies and indicate what else can affect the successful execution of this code portion. It's one of the darkest routes to try to trace a problem which cannot be caught by a compiler but comes from the organizational level. You only find it when you know it or take a lucky guess. Better write a good explanation sparing your new colleague hours and days of painful debugging.

Write use case guidelines

I like to think of them as of stories, or, in other words, use case descriptions. If you paid attention, most books on popular technologies provide code examples. But not just examples of how to use a particular class or how to properly call its methods, but how to complete a small task by orchestrating the framework components together. This strategy introduces the reader not just to a particular code element, but to a small family of interconnected components and their relations. Even better, learning components in some usage context makes the knowledge stick, while passive description of code elements and architecture is likely to fade away if it doesn’t find application soon.

That's one approach which you can and should adopt. You certainly have such standard scenarios in your everyday routine. How to send out emails. How to add one more scheduled service to perform some regular repeated activities. How to invoke update of certain data. What steps to take in order to perform data model update and data migration on a production system? How to expose new functionality via web service? These are typical scenarios which require knowledge of several parts of the system. It seems transparent to an experienced team member, but can be very shadowy to newcomers. So take your time and write such guidelines for typical scenarios. Tell your colleagues to do the same once they stumble upon a routine task for the next time. Encourage new team members to describe these stories once they mastered them. After a while, you would have accumulated a knowledge database without noticing it.

Install a wiki

Accumulating knowledge in written form is a great beginning but it serves no purpose if the documents are stored on your local machine or buried on your internal FTP server people don’t remember the path to. Bouncing emails with attached documents between team members doesn't work either. Documents get lost in thousands of emails and attempts to version them over that medium will turn you gray. The information needs to be communicated to outside, where it can reach all involved parties and shared so everyone can become a contributor. A wiki is by far the best way of achieving this objective. Get some wiki software and install it on your local network. If you have multiple offices not interconnected into a VPN, consider a public wiki protected by user logins. Important thing is, there is a knowledge sharing medium and it's accessible by all team members, just like Wikipedia is open to everyone in the world. This way everyone can get to the knowledge they seek, update the information when needed and share their own knowledge and experience with the rest of the team.

Install forums

This especially makes sense when you're a big or even a distributed team. Often there is an issue that has to be discussed and documented as such. The format of wiki may not work perfectly here, so you can stick to the old and proven medium of discussion forums. When experience is documented in this manner, new team members can easily follow the learning path the other person went through and come to the solution without repeating all those steps themselves.

With a big organization, it can often happen that one team or department provides services or products for another. Here forums can play the role of the written customer support. One person asks for assistance with adopting some component or properly setting up some workflow. The answers from the developers' team and online discussion on the matter would serve greatly to preserve the knowledge about the component and gather working experience with it in one place. Other people can now easily follow these guidelines and developers have a clearer picture of what real world issues their users are facing and what to pay attention to with further development of the component in question.

Make the information discoverable

Integrate your various information sharing tools into one portal. Add a search over all portal parts. Structure contributions into categories. Use tags to quickly organize the information pieces. Add related items functionality to bind related articles and relevant contributions together. Integrate it with your project and task management software and link portal contributions to tasks and work items. That will help better understand the context and the origin of the problem at hand. Integrate portal with your online documentation system if you have it. Link contributions to code components and mention dependent or related components to help better understand system architecture. Providing developers with needed information right there at their finger tips will definitely spare them many hours browsing through source code and debugging this. Again, for the Nth time since the other developer followed the same steps before. Just like the developer before him did.

Motivate people to document and share their knowledge

Find ways to encourage team members to contribute to the knowledge base. Talk about the importance of having the project knowledge in written and accessible form. Let them take moments from their working hours to write documents, since nobody is going to do it on their free time. Offer them some extra benefits. Remunerate extra people taking a leading role in the management of the documentation. Recognize in public the most actively writing team members as playing one of the key roles in the project. Don't let the idea of efficient preservation and sharing of the team knowledge burn out and fade away.

Because if you fail at it, then you will be seeing frustrated faces on a regular basis and might discover new team members hanging out on the web asking questions like this one:

Hired as a developer to maintain and update current code base, no docs!