How can I become a better communicator?

Question

Sometimes it takes me two or three attempts to explain how a piece of code functions or how a process works within an application so that the person I am speaking to understands (or at least responds as if they understand).

I'm reading a few different books on Technical Writing but what can I do to become a better verbal "code communicator"?

Answer 1

I would consider the design of the code that I am trying to communicate. There have been volumes written on this in the Microsoft .NET world in the form of the framework design guidelines (also available in book form). I have found that code that meets those guidelines is very easy to communicate and explain to other developers, and even end users in the form of release notes.

Answer 2

From my own personal experience it's all down to time and getting to know your clients.

Overtime I have developed way to explain technical things in a simple way for the end user. I've not always been able to do this, but after working with a lot of end users, I have managed to simplify description.

Although, some people will still never understand!

Answer 3

Patience is the key. As long as you remain courteous and patient you and the person you're explaining to won't get frustrated. Also, concrete analogies are a big help - try to tie your code's operation to something they already know.

Answer 4

1. Make sure you understand what the code is doing yourself. Often I find if I am having real problems, then it's because I don't know.
2. Try and imagine you are explaining it to a 6 year old. It may be helpful to explain it in a way that expresses the code as real world objects that we all know and understand (by this I mean keep it simple - not make it stupid!).
3. Expand your own vocabulary, to a point. Use common words that most geeks would understand (like "semantics") but you don't need a PhD in English to understand.
4. Talk more about code. As coding more improves your code production, talking more about it will improve the quality at which you explain it.
5. Visualise the code human beings think visually, if you have a better visual representation, you will probably be able to describe that better than words.

Answer 5

That largely depends on your audience and how well you know them. I find it's best when talking with non-technical people to explain things in the most general terms and expand on that only if they request. Example:

"This web service will receive a request for information and return what was requested."

If they need more technical details they will ask. Or you'll see that look of bewilderment on their face.

Don't make the mistake of assuming they're stupid; just keep it simple and accurate and they will tell you (verbally or through body language) if they aren't getting it.

I will also follow up with an email recapping what was discussed and offering to fill in any gaps.

Answer 6

I find that people respond much better to visual presentations than just listening to a talk. I don't mean to imply that you should just walk them through the code as that would put them to sleep. What I mean is that showing them a picture of how data moves through your code will help the understanding of the code. A picture is worth a thousand words after all.

Answer 7

To all the excellent comments above I would like to add one more very important one: practice. Always take every opportunity you get to present things. Whether it is just by writing a document to actual presentation - all forms of presentation are important. There are not that many programmers who can write documents that other people understand, same goes for presentations so its a great skill to learn.