Dear Diary: Writing Updates, Comments

3 Jul 2012 Some folks hate to write. It's not in their nature. I understand that. However, that can't preclude proper communication. This is true for any medium, be it comments in code, sending emails to coworkers, or updating a support ticket.

I often hear from sysadmins that they don't know what to write and therefore they send terse, unclear messages, or fail to leave comments in their esoteric (and desperately needed in times of emergency) scripts. I often tell my team to pretend they're logging to their daily journals. So I recommend:

"Make it a Dear Diary moment."

But, instead of writing about what they wore today, they should write about anything that seems relevant to what they just worked on. For example, after a recent coding session, I wrote the following git commit message:

Checking in as I'm getting sleepy. Note I need to think about the design of getDeps() a little more thoroughly.

The next time I picked up that project, I remembered where I left off (I always check my git log) and what my intent was before I wrapped up the last time.

The point is this: Write something. ANYTHING. And often. The more you write, the better you're able to write (relevant; topical; appropriate) updates that provide context and make sense.

So, get writing.