How do you go about introducing the codebase, which may be rather complex and tangled with a lot of gotchas, to a new member of your team?I think the easiest way would be to have the overall architecture laid out with diagrams, and take a couple weeks (or months) giving the new person well defined (and well scoped) tasks as he becomes more accustomed to the code.However, as a consultant (and junior employee, at that,) I can't always have that either due to time constraints or team role designations. (I have been on this particular project twice as long as anybody else, so junior is in no way knows less about the code/project.)I've been tasked quite a few times now to introduce a new member to the project and code, and sadly each time I find I'm not much better at it than the one before.  I love diagrams and pictures, but often feel that they don't adequately account for the complexity in a system.   (What about all the little's gotchas?) The project is getting to a point where we will be handing it off to the client, and to make things more challenging, the person I'll be doing a knowledge transfer with is essentially just out of college.  (Not that I'm much better when doing knowledge transfers with senior developers.)I attend a user group once a month and other opportunities as they arise, so I'm not unused to be being introduced to new topics, but feel my ability to replicate effective knowledge sharing woefully inadequate.Any advice would be greatly appreciated.  I am looking mostly for a guideline I can follow.  For example: Where do you start? How do you proceed? How do you cover unfamiliar technologies or patterns on the listener's part without taking all day?  Where do you tie in business logic vs. code-structure?Thank you!(As always, please feel free to edit the question as you see fit.)
How to introduce code to a colleague
communication
Step one is of course to remove the gotchas from the code. Clear, concise, consistent code is easier to get into, work with, and debug.Where do you start?I ask the newcomer how they want to get into the codebase. Everyone learns differently. Some people like having little tasks to work with. Some like debugging existing code. Some want to see the code running to understand what it does. Some want to start at the entrypoint and just navigate around. Some want visio diagrams...  No set pattern is going to work best for everyone.How do you cover unfamiliar technologies or patterns on the listener's part without taking all day?I avoid them. Let them be black boxes until the newcomer asks about them. Then provide just enough information to get the jist of it, with the hint that they can learn more on their own time, or ask later when the general stuff is more well known.Where do you tie in business logic vs. code-structure?I try not to. It's almost always better for the newcomer to learn on their own so that it sits in their mind in a structure more natural to their way of thinking.One thing to remember is to keep the instruction short. People tend to check out pretty quickly, so any more instruction at that point just doesn't 'stick'. Show them things for 15-60 minutes (different people have different attention spans) then take a 5-30 minute break for them to process it. 