Another entry from my internal blog at Socialtext which i think is relevant to the rest of the world.
-----------------------------------
I had a meeting this morning with Ken to discuss the way our app currently defines permissions and roles, in order to clarify, standardize, and regularize the way we store this info (as I move it into a DBMS).
At one point during the meeting, I was explaining what a permissions named "login" meant, and I realized that it was just badly named, and should be "edit_controls", because it was really about whether or not the user could see editing controls, not whether they could login.
This sort of thing has happened to me many times, either as part of discussions or when trying to document something. I realize that my naming scheme, or my API, or whatever, was not quite right. The act of trying to write down an explanation of what something is, how it works, or why it is the way it is, can cause you to rethink the thing itself.
I know that I have often sat down to write docs for a module's API, and realized that I could not document it clearly. This means to me that the API is simply not right. If I cannot explain to someone else how to use my API, then it must be wrong in some way.
Forcing oneself through the additional step of explaining your work to someone else is valuable, not just because the other person will gain new knowledge, but because you will be forced to think about the work you did in a new way. This is a different perspective than the one you had while doing the work. In particular, the amount of context you can carry around in your brain while coding is often much more than you can communicate to a reader. So that communication often causes you to rethink, simplify, clarify, rename, and so on, making for better code, code that you will be able to better understand later, that others will be able to follow more easily, and so on.
