How do I get people to stop bikeshedding (focusing on trivialities)?

Question

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 (members of an organisation giving disproportionate weight to trivial issues) 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?

Answer 1

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.

Answer 2

"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.

Answer 3

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"

Answer 4

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.

Answer 5

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.

Answer 6

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...

Answer 7

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.

Answer 8

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.