Ways to improve your articulation or explanation of code or processes?

Question

I have a hard time explaining code or different development paradigms such as design patterns, etc. In my mind, I know what I am talking about, but when I am explaining something I did to a senior or a peer, I feel I am not being as articulate and therefore not doing justice to them. Sometimes, I feel as if I am trying to hard to explain something or making something more difficult that what it actually is. How do you approach explaining code or other practices to someone or a group of people? What are ways you have improved your articulation of code and practices? Does confidence have anything to do with this?

Answer 1

One way to start would be to write out what you are trying to explain for yourself. If you can't write out something that you did and explain it in such a way that it makes sense to you, then you probably didn't really understand it in the first place.

This method will also help you to break down ideas in your head into concrete components. Explain bits and pieces of the whole, then tie it all together to show how the "system" works. With practice, you can use this methodology to break ideas down when you explain them to others as well.

Answer 2

This is true about teaching and explaining things in general:

Try to put yourself in the listeners shoes. Figure out what they know and what they don't know. If you are explaining a design pattern to someone who does not know programming, then explain the broad terms, not the details. If the person is an experienced programmer, then you can explain it in detail. Always keep an eye on their reaction to what your saying, like facial expressions. This will tell you if they understand what you are explaining to them. If they don't understand one thing, you need to explain it either in more detail, or skip it, if it is not important. Don't repeat what you are saying. If the listener doesn't understand something, saying the exact same thing again isn't going to help. Instead try to explain it from another angle.

A good idea is to explain things using metaphors. Know your listener, and find out something they understand well. Then explain the process or code using that metaphor. For example, I usually explain how TCP packets differ from UDP packets by explaining how we talk on the phone. Similarly you can explain how TDMA and FDMA works as a group of people sitting around a table talking to each other at the same time. When using metaphors you need to drop the technical terms until you know the person understands how it works, then you can drop the metaphor and explain in terms of the actual code or process.

Answer 3

My personal experience about this:

• Use diagram more than words, or talking. A good diagram worth thousands of words. Although others may not understand the detail, a diagram can give them a high level idea of how things work.
• Start with something that the audience can understand, and evolve your solution. My favourite Design Pattern book, 'Head First Design Patterns', is a typical example about this.
• Make sure everyone is on the same page. Make sure everyone understand the problem before you go into the solution. This sounds really stupid but you cannot imagine how often that people start the discussion with 'OK, let's do something like this ... ' without clarify the problem beforehand.
• Seeking feedback. Everyone has its own problem about presenting ideas to others. You have to ask your audience about their feelings - too fast? need some check point in the middle to clarify questions? etc.

Answer 4

This is a great question. I don't think computer science majors get enough experience at public speaking and defending their code in college. At least the ones I have interviewed haven't. Here are my thoughts on this.

1. Listen to what your co-workers are saying, and work hard to make sure they know that you understand their point of view. You can't change anybody's opinion if they think you don't understand their starting point.
2. Read design patterns book, such as Design Patterns in Java . How they explain theories will help you learn to articulate your own.
3. Take a public speaking course. Getting passed the nervousness is a big one.
4. White-board out your ideas, visual aids are an immense help.