Importance of communication and how to improve it

[Grelbr42]

So the generic question here is, how to improve communication?

Recently I started a review task for a coworker's analysis. One of the items in the report for the analysis is a graph with a linear fit of some data. And the linear fit has uncertainty reported in the fitting parameters. So I ask "What did you do to produce these uncertainties?" His response is "I calculated them." Um... Click click click. "Yes, but what did you *do*?" So he starts to show me his PERL script. "Wait. OK. What does the PERL script do?" He tries to show me more script. "No no. Source code is not documentation." He looks quite upset with me but pauses. "What does the script do to calculate the uncertainties?" Suddenly he's back in the groove, walking me through 200 lines of PERL. And suddenly I see that he has included a covariance matrix. Sigh. I know what the client will do with *that*. They have a very large pile of such things behind their facility. On the far side of the parking lot behind the trees. "So you used the textbook formulas, fed the data in, and got reports of the uncertainty of the fitting parameters, yes?" Well... Yes. But my PERL script... "No no, that's quite alright. I have what I needed."

How could I have asked this question so that my meaning got through?

 

[Haborix]

If this is the first interaction of this sort, then I think it is natural to have some iteration on questions to get to the heart of the matter. I suppose in this instance you could have asked what type of uncertainty or equations are implemented by the code. You kept asking what he did, and he definitely wrote code. You also asked what does the script do. These are all easily interpreted to require answer that talk about the script.

 

[berkeman]

"No no. Source code is not documentation."

Was the code commented? Was there a good summary of the code in the comments at the top of the file?

 

[jrmichler]

How could I have asked this question so that my meaning got through?

Be careful. You could find yourself with the added responsibility of supervising this person. Extra work, much frustration, and at the same pay.

Some suggestions:

What is the algorithm implemented in your code?

Sketch the flow chart of the your code.

Sketch the flow chart of the algorithm in your code. Yes. Now. Freehand.

 

[Grelbr42]

Was the code commented? Was there a good summary of the code in the comments at the top of the file?

No comments whatever. Variable names like xj and yq.

 

[phinds]

How could I have asked this question so that my meaning got through?

"What underlying methodology did you use to base your calculations on?"