“Clarity” is a great word. I use it when my head’s in code-space, meeting-space, or I’m indulging in some other form off geeksqueal to remind myself the things I know may be things someone else doesn’t know they don’t know, and I really need to stop and make sure everyone’s on the same page.

There’s a more complete discussion of that thought by Steve Schwartz in his post, No One Knows What the F*** They’re Doing (or “The 3 Types of Knowledge”). It called to mind news articles discussing the research about completence floating around a while back that seemed to boil down to: competent people question their competence, less competent people don’t.

It’s interesting how being forced to explain something helps bring a whole constellation of things you thought you knew into sharper focus. I like to think I helped create better documentation (and better software) by making the developers expain what they thought their code was trying to accomplish rather than just what it did. I always found it gratifying when the engineers felt they had a better understanding of their project after “the docs guy” forced them to explain it.

I try to keep that in mind when someone trys to make me explain my code, too.