code-as-documentation

Documenting Everything

Currently, I’m taking the second quarter in a two-quarter series on Systems Analysis. One of the lists my text presented is “7 Design Habits”. (side note: I appreciate the reference/nod to Steven Covey’s 7 Habits Of Highly Successful People). I like the list, so I wrote it out on a post-it and have it on the wall next to my desk.

  1. Understand the business
  2. Maximize graphical effectiveness
  3. Think like a user
  4. Use models and prototypes
  5. Focus on usability
  6. Invite feedback
  7. Document everything

I value each of these. While maximizing graphical effectiveness has been an area of interest for quite some time (it’s the roots of my interest in design), what really speaks to me right now is “document everything”.

I’ve lived by this mantra for years. I try to drop everything into Evernote*, for instance. Articles I’ve read, people I’ve met, things told to me. This collection of notes is but one element of documenting everything. Knowing where I got ideas is pretty important. But this notion means more. To me, it implies a certain thoughtfulness to the documentation. Sure, it’s great to have dozens of pages of random notes. But “documentation” is organized. Not just links to articles, or pages of feedback, but also analysis, explanations of the “why” within choices. Being able to reference, at some random point in the future, how we got to a certain decision can be crucial when evaluating a problem and determining a response. Also, in a more negative vein, it can show due diligence in a lawsuit.

So, yeah, my propensity for collecting information has saved me plenty of anguish over the years (“you never told me that!” “well, here’s the email I sent to you with your reply”). It’s also been helpful to friends and colleagues (“hey Carl, who was that guy from Facebook we met with last year”. Yeah, it’ll be in my notes). I appreciate the reinforcement that this is a best practice that’s valued at least by textbook writers.

*this link to Evernote is an affiliate link. If you subscribe to the service, I will get rewarded with a free year of the service.