Some time ago, I came across Kidlin’s law – a problem written down is a problem halved. This tracks well with my own experience, but why is that the case? In a nutshell, in order to write something down, you must understand it well enough to write it down. I often find that, when describing a problem in writing, I add details that I knew – but weren’t conscious of.
Combined with a structured form in which to describe the problem (and my favorite is the Kepner-Tregoe red card), I have found this to be an excellent exercise, both in terms of helping me solve the problem, but also in terms of the ability of others to solve a problem which I can’t solve – whether it is due to a lack of knowledge or a lack of access.
It comes, however, at a cost. It takes time and effort. Whether or not it is worth that cost is something one must evaluate at a case by case basis. The way I see it, there is little to no reason to do so if the issue is one which has been seen a number of times before. That information should already be documented, in accordance with the second principle of the Hacker attitude.
On the other hand, a novel issue – or an otherwise well-known issue forwarded to someone who is, as yet, unfamiliar with it – has something to gain from being thoroughly described. In the first case, the reason should be obvious; a novel issue must be well-described in order for a solution to be reached. In the latter case, it is a question of being both a good colleague, and sharing one’s knowledge so that others may learn.