Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I have been tasked with teaching other teams a new codebase, but I keep running into an issue. Whenever I go to actually walk through the code with people, we don't get very far before the entire exercise devolves into a bikeshedding exercise. Since they don't know the codebase, but think they need to help improve it, they focus on the things they can understand:

Why is that named that? (2 minutes to explain why it's named that, 10+ minutes debating a new name)

Why is that an abstract base class rather than an interface? (2 minutes to explain, 10+ minutes debating the relative merits of this decision)

...and so on. Now, don't get me wrong - good names and good, consistent design are important, but we never get to discussing what the code actually does or how the system is designed in any meaningful way. I've done some meeting refereeing to get people out of these tangents, but they're gone - distracted by what the code will/should be when their pet triviality is fixed, and they miss the bigger picture.

So we try again later (or with a different part of the codebase) and since people didn't get enough knowledge to overcome the bikeshedding effect, it repeats.

I've tried smaller groups, bigger groups, code, whiteboarding, visio diagrams, giant walls of text, letting them just argue it to death, cutting arguments short immediately... some help more than others, but nothing works. Hell, I even tried having other people from my team explain it because I thought it might be that I'm just bad at explaining things.

So how do you educate other programmers enough that they stop fixating on trivialities and can meaningfully contribute to the design?

share|improve this question
38  
I hate to say it, but it sounds to me like this phenomenon is illustrating more of a problem with the codebase than with the newcomers. –  NickC Nov 21 '13 at 2:27
27  
Have you tried deferring questions to the end? "Hang on for a few more minutes and I can explain at the end" and then just pushing through the rest of the content. Perhaps some of these questions will answer themselves –  jozefg Nov 21 '13 at 2:36
20  
@NickC, I believe that whether the code is good or not has nothing to do with how you get to understand it, how you manage to get a clear big picture of it. Wasting time on small details from the get-go without taking the time to get an initial big picture is bad and will never help in fixing that potential bad code. –  Shivan Dragon Nov 21 '13 at 15:31
10  
What is the goal of teaching someone the codebase? Maybe you can communicate that goal more clearly, and why it's important, so that they can see that debating a new name for an object is distracting from that goal and should be reserved for another meeting. –  LarsH Nov 21 '13 at 16:53
49  
There's good advice in these answers. I would briefly add: consider using "process" as your ally. When someone says "this design is suboptimal" the correct response is "excellent, I'm glad you noticed that. After this meeting please enter a bug in the tracking database with a detailed description of the problem and your proposed fix. The triage team will review your proposal, prioritize it against the rest of the work items, and assign it to an appropriate developer to fix it once all the higher-priority items are fixed. Moving on..." –  Eric Lippert Nov 21 '13 at 22:09
show 4 more comments

8 Answers 8

up vote 140 down vote accepted

I think the problem is the task: "I have been tasked with teaching other teams a new codebase".

You have been given the wrong job, or maybe misinterpreted the job you've been given.

By presenting at the code level, you invite code level thinking.

Start at the system level and present the design and the design choices that were made. Don't allow extended discussion: you are not reviewing it. Do allow questions: you do want them to understand the system. If people "would have done it differently", fine. Maybe agree. Or not. But move on. It's the way it is right now.

When you get to the code level, you will have already got them primed with the system terminology. The names (I assume) will make sense. Same as above: no extended discussion, questions for understanding. Move on.

Now set some class problems to work through. How can we make enhancement X? Choose something non-trivial that "goes with the flow" of the system design, and work through what you would change. They should be getting the rationale of the system now. Choose another enhancement that could break the system if done wrong, and show how it can be done right. That should be an Ah Ha moment for them. Some might even beat you to it!

It's a tough gig, especially after the false start you've had. Sounds like you've invested a lot of time and effort already, and maybe there is a bit of a me versus them feeling. 'Fess up, and start again. We assume that they are smart people. Give them the challenge of thinking at the higher level. And break up the groups that already exist by selecting different cross sections of teams for the new sessions.

share|improve this answer
2  
I have done a bit of high level design instruction first, as well as training on some new/unfamiliar technologies (IoC containers, dynamics) to help prep. That training has gone pretty well. It is a good point to raise. –  Telastyn Nov 21 '13 at 3:49
    
+1 fot not trying to fight with people with "psychic hacks" like "I'll answer your off topic questions in the and at your time!" but rather changing the point of view –  Buksy Nov 23 '13 at 12:05
2  
Fantastic answer. I especially like the suggestion of making the focus be 'what it does' rather than 'what its internal components are named'. –  Daniel Hollinrake Nov 27 '13 at 14:38
add comment

"Park them". At the start of the lesson, explain what you are to discuss, and clearly explain what is considered Off Topic. If you are asked a question that is clearly OT, say so and move on. If they come back to it, write the question on a whiteboard (This is critical) for later discussion and move on. At the end of the lesson, when they are on their own time, not yours, watch how quickly those questions get resolved.

share|improve this answer
8  
+1 That way people feel they are not being ignored. –  andy256 Nov 21 '13 at 3:44
    
I agree with this. IF the problem is discussing irrelevant things for too long then don't discuss irrelevant things... –  Chris Nov 21 '13 at 9:31
5  
Maybe rather than taking everyone's time by writing OT questions on a whiteboard, ask the questioner to take note of it (on a designated wiki page, JIRA issue, wherever). –  LarsH Nov 21 '13 at 16:55
11  
I think the physical act of taking a moment to write their question on the whiteboard clearly shows the questioner that you're deferring their question (rather than ignoring it) and shows to the rest of the audience who is asking all the questions and thus delaying progress. –  JBRWilkinson Nov 21 '13 at 17:15
1  
@LarsH - exactly. By putting on the white board, for all to see, the conversation is stopped. If it comes up again, the instructor just points to the question and says "I promise we will come back to it". –  mattnz Nov 23 '13 at 6:41
show 2 more comments

Set expectations correctly and be honest, open and upfront.

Make sure your goals are open and transparent.

Start off discussions with the high level view as promoted by andy256 (+1) but also make sure that you include your objectives, e.g.

"...as we look at this issue, lets make sure we don't focus on x, y and z. Let also make sure that we're not looking at at implementation details such as a,b,c or trivial details such as j,k,l. I know there's bound to be a lot of details in the code and details things that could be addressed, improved or made more standard, but lets try and look at what it's really achieving at a higher level first"

share|improve this answer
1  
+1 open ... transparent ... objectives –  andy256 Nov 21 '13 at 3:42
    
+1 for the first 2 sentences. However, telling people to not think of something is not a good way to get them to not think about it. "Whatever you do, don't think about pink unicorns." Before I mentioned pink unicorns, were you thinking about them? Probably not. If instead I said "Lets not get distracted by imaginary animals and instead focus on Australian animals" then koalas and kangaroos might have occurred to you, but probably not pink unicorns. –  Michael Shaw Nov 22 '13 at 4:14
    
Good point. However the real point is not to stop people thinking (and not said) but to avoid people getting into those protracted conversations that are meeting killers and morale suckers. People will always think a lot of unsaid stuff. That's ok. In a professional business situation some things are said and many not. –  Michael Durrant Nov 22 '13 at 4:23
add comment

So how do you educate other programmers enough that they stop fixating on trivialities and can meaningfully contribute to the design?

First, don't think of their concerns as "trivialities" or "bikeshedding". Those are judgmental words, and they're insulting. Their concerns are valid. They're just not important at the moment.

The key to any good meeting is for everyone to know:

  • why you're having a meeting and
  • what you hope to get out of it
  • how long it should last

State these things up front, explicitly, and explain the goals.

For example, you might say: "This meeting is for me to familiarize you with the Foo package and how it's used in our reporting module. My goal is to have you understand enough about Foo that you can work on the Bar Reports project coming up next week. I'd like us to be done in the next 90 minutes."

Then, when a topic comes up, it might go like this:

New person: "Why is FooWidget implemented as a facade pattern?"

You: "Well, I think it's because (short explanation of design decision)" or "I don't know."

If the answer is enough, that's great. If not, and it continues:

NP: "Don't you think it would be better done as a singleton?"

You: "I hadn't really thought about it, but I'd like to keep moving ahead with explaining how FooWidget works."

NP: "But if it's done as a singleton then we can--"

You: "I'm sorry to interrupt, but I need to keep this focused on how FooWidget works. This meeting is only scheduled until 11:00 and we have a lot to get through. The design discussion will have to wait for another time."

After you go through that once or twice, you can shorthand it to "That's outside the scope of this meeting."

Note that you are not saying "That's dumb to worry about" or "It doesn't matter" or "Shut up" or "You're too new to have input." You're simply focusing the meeting on what needs to get done and the time involved.

share|improve this answer
1  
It easy to tell when a presenter really is not interested in feedback. Those meetings go fast. No one cares. –  chux Nov 22 '13 at 4:47
add comment

In certain organization you are never going to be able to achieve this. Many organizations value political wrangling and ladder-climbing way more than intellectual capacity, diligence, and loyalty. And why wouldn't they. Ladder-climbing puts people in positions of power, allows them to enhance their personal lives with more discretionary income and really never becomes obsolete.

Contrast this power-wrangling with actual problem solving, abstract thinking, and making decision on tough issues that they may be responsible for the consequences of later, and many employees weigh heavily on the side of trying to bikeshed as much as possible.

The only advice I suggest is that you make it crystal clear, in the context of your organization, if possible, that these participants personal fate depends on their comprehension, contribution, and effort toward the real problem you are trying to solve. If that's the enterprise architecture, expressed in this -errant-codebase and all it failures, that's it. Make it clear to them that they must provide substantial meaningful input about that. Not some other randomness, that happens to be a pet-peeve of a senior somebody or other and will gain them nice brownie-points by agreeing with said senior somebody on.

This is often hard to do, as the senior somebody usually doesn't understand the technology going on, isn't interested, and unfortunately, controls the raw-ingredients: employee time; hire & fire, conference room politics, promotions, etc., etc. seriously, et cetera to the nth.

share|improve this answer
add comment

What you call bikeshedding, I would call converting someone's flow of thoughts into our own. By discussing names, patterns, they get to understand the code into their own terms and there isn't any way to prevent it, it is needed.

Besides, there isn't any need to go for a very detailed walkthrough of a whole codebase, because details will be forgotten long before they get to work on it.

Based on these two ideas, I would suggest to break up the code base into units, and the learners into two-people groups. For each unit of code, each group will have, say 25 minutes (depends on the LOC of course), to be able to do a 5-10 minutes walkthrough of the code to the others. Three minutes of questions and repeat with the next unit. Explain is the key word; they have to ensure the others have understood all of it.

You would be only there to enforce time, no off-topic and control the unit has been understood enough. They will be actors of their learning and will be more focused on explaining to the others than bikeshedding.

You may require a high-level hand drawn schema from them of the code unit, which will be copied and kept on the team-shared documents, so they have something tangible to refer to in the future. That's good to anchor memories too.

Sorry if you have already tried that...

share|improve this answer
add comment

Have you tried making pre-lessons that people look over individually?

Make short videos or presentations that explain the content, how the code works, or basically all that you want to teach them in a format where they need to look at it on their own and learn the information you are trying to teach them.

Then you use the team-based sessions to discuss issues related to the content. You need to distinctly identify that the team sessions are for discussing and troubleshooting issues related to the content only.

If you provide the lessons to people on an individual basis, you may be able to avoid that other social issue where a single matter can become the voice of the group as a collective and distract away from the actual purpose of the lessons.

share|improve this answer
13  
Nooo......., not videos..... "Death By Powerpoint" has been superseded by an even worse fate......, Although it will have the desired effect of stopping questions - threaten them with more videos that take 10 minutes to explain what can be read in 30 and understood in seconds.... –  mattnz Nov 21 '13 at 3:38
6  
+1 mattnz Communication issues are unlikely to be improved with one-way interactions. –  Michael Durrant Nov 21 '13 at 3:41
1  
I don't want to be paused even if I'm in a video! What video format/codec disables pausing? :) :) :) –  Kaz Nov 21 '13 at 6:23
add comment

Try teaching them the design of the codebase first, guide them round the architecture, BEFORE you start looking at specific examples. That way they might see how the code examples you look at fit into the bigger picture. Think about how your training programme is structured. And include the business motivation behind the design.

I spent several years training other developers, and I never went into the code before showing them how the system fitted together. Then when I got them doing code exercises in the framework the questions were structured and on-topic.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.