

Sometimes, The Better You Program, The Worse You Communicate - aycangulez
http://www.secretgeek.net/program_communicate_4reasons.asp

======
10ren
I've been writing up some of my research recently, and when I go back to it
after a month, the examples are the most helpful part; second is psuedo-code.
That's so far, anyway.

I'd actually gone to a lot of trouble to define input and outputs precisely
(in set notation, using LaTeX), and defining explicit constraints/relations
between them, and even outlining proofs. This was a lot of work, and the
process did increase my clarity of understanding, but it hasn't helped me at
all in reading it - in _communicating_ to myself. I guess proofs are primarily
about proving, not communicating. Another problem with proofs is that the best
way to conceptualize/visualize an algorithm for the purpose of proving it may
be quite different from the best way to grasp it intuitively. Proofs are not
primarily operational.

Re: defining terms in the article: I think metaphors can act like definitions
of terms, and are very helpful for communication. An apt metaphor can imply
all kinds of behaviours and interactions that the reader already knows,
enabling them to quickly grasp your meaning in a few words. I think it's
arguable that our thinking is actually metaphorical, in that we interpret new
ideas in terms of existing ideas; even to the point of tools being
neurophysical extensions of our arms. The difficulty with apt metaphors is
finding them; and before you can do that, you need a _very_ clear
understanding of what you mean. Improving my own understanding is probably the
best way to improve my write up of it... though, writing it up definitely also
helps improve my understanding, as implementing it also does.

\---

So, an iterative back-and-force process between notes, writing, thinking and
implementation is probably the most effective route to clearer understanding
and therefore clearer writing.

