So here is the story. I have a coworker. He is a smart guy and a good programmer. In terms of writing good code. However he is a terrible communicator. And communication is very very important in software development nowadays. It is one of those values emphasized by XP authors.
His communication has two problems:
1. There is a lot of it.
2. It is inefficient as hell, because he never reaches the purpose of communication - i.e. making other person understand what you really mean.
Thus he mainly like mumbles to himself, although involves other people ears (or well, in my case - eyes, as we chat on Skype most of the time).
When he develops and shares with me his thoughts and doubtful parts of his code, giving little to no details or context, or in other cases giving too much details, but still not the relevant ones.
When he posts bugs/requests on the issue tracker to some other developers - the same story happens there. His stories miss the relevant details and contain a bunch of stuff understood only by him.
Today once again the co-programmer from another team commented on his issue:
I need MORE details. What does the current response look like? What are you saying it should look like? What exactly needs to be added to the SDK?
An issue needs to have at a minimum:
- A brief description of the problem.
- A set of steps to reproduce this problem.
- What the current results are.
- What the expected or desired results are.
And so my coworker asks me: "Uh oh, is my English so bad, that I didn't make myself clear enough?" Well the problem is that he wouldn't make himself clear enough even in his native language...
To be efficient in communication the only guidance I can give him is:
Do not make any assumptions about your companion's knowledge of the issue. Instead give him the minimum but most important details and context - then guide and point the companion precisely to the very very point where the issue is.
The best is always - demonstrating an issue by example:
1. Use screenshots - and point with arrows where exactly the issue is.
2. Use videos - show what's going on with a mouse pointer (or other ways).
3. If we are talking code, cut and paste a code and highlight the relevant spots.
4. If we are talking http requests, show request/response examples - and highlight the important parts.
Remember: A picture is worth a thousand words
