Document the Why, not just the How

Documentation is important. Everyone knows this, everyone agrees with this, it’s not really a topic of debate. It’s important to have your processes written down in some format to make ongoing work easier. If Person X wins the lottery and promptly quits, never to be seen again, can their duties be picked up by someone else relatively quickly? If you have good documentation, hopefully the answer is yes.

Unfortunately, documentation is too often confined to the how of the work, and leaves out the why.

Sure, you can lay out a step-by-step process of how to do a given task. That’s easy. I’ve written a great deal of process documentation in the last several years, with the intent of making life just that much easier for the next guy who fills that role.

What’s too often lacking is an explanation of why something is set up the way it is, or why a process has to be done a particular way. Maybe there’s a lot of tribal knowledge in your organization that covers these questions, but until someone documents that, it’s essentially useless.

If we don’t explain why a decision was made that led to the current state, it becomes much harder to work towards something better. Maybe there was a significant problem discovered along the way that required doing it a particular way. Maybe it was a budget constraint or lack of available resources. Maybe it’s just that no one thought of doing it any other way and that’s the way it’s always been done.

If no one documents the reasons, you’re condemning the next person to re-invent the wheel, to catch Sisyphus’s boulder and roll it back up the mountain themselves.

// Dear maintainer:
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
// total_hours_wasted_here = 35

What is the best comment in source code you have ever encountered?” on stackoverflow, via the Internet Archive since the original thread was removed

I’ll be making an effort to include more of the why in my own documentation as part of my ongoing work, and for great justice the sake of your sanity and your successors, I’d encourage you to do the same.


It’s not easy to “check out” but you should do it anyway

Julie at Boelter + Lincoln writes:

Here I am on vacation in the Northwoods writing this blog. I will be on vacation all week and will check my email every day – several times. I will log in to check on client campaigns and meet deadlines that could probably wait a few days. I am not an on-call rescue person, I work in advertising. But we have been conditioned to be connected all the time. What if I miss something?

– Can you “check out”?

My rule is very simple: if I’m not in the office, I’m not working. Obvious exceptions apply: those days when I’m just sick enough to stay home rather than infecting everyone else but not sick enough to be bedridden, days when last night’s blizzard buried my car in three feet of snow, and so on. But otherwise: no office, no work.

When I leave at the end of the day, my work laptop gets turned off and put in its bag. I don’t have a corporate-issue cellphone, so there’s nothing to persistently ding with each incoming email. The laptop doesn’t come out of its bag until the next workday morning. Once I’m across the front lobby threshold and into the parking lot, it’s me time.

However… I recognize that there will occasionally be instances where something needs to get done outside of business hours. If that happens, someone has to contact me directly. There needs to be a phone call, or a text message, or – depending on who’s asking – a Twitter mention or message. It needs to be initiated by someone from work; I won’t be actively looking for something.

It’s simple, but actually quite effective. My boss is well aware of this policy – it was made quite clear my first day on the job. If you really need me to do something, no problem, but it’s not happening unless you get in touch directly. I’m checked out otherwise.


Make 2012 a year of less and a year of more

I want 2012 to be a year of less, but also a year of more. This isn’t as contradictory as it might sound.

Less complaining

We as a people complain a lot. Admit it. Even during Christmas, heavily marketed as the season of giving and good cheer, there was no shortage of complaining about what people got versus what they wanted.

2012 needs to be a year of less time spent bemoaning our own first world problems and more time spent enjoying what we are fortunate enough to have:

The 99% in America are still the 1% to much of the rest of the world; it would do us well to keep that in mind.

Less spending

We’re currently in the midst of one of the worst recessions ever, and no one seems to be able to agree on whether it’s getting better or worse. Unemployment is at its highest in decades. Many people and families are struggling to get by on wages too low for the endlessly rising cost of living.

I’ve been extremely fortunate in that I’ve never really been poor. My family was certainly never wealthy, but we always had enough. My parents taught me to be responsible with money, to stay within my means and to realize that there’s no need to always have the latest shiny thing. I’ve also been fortunate to have and keep a steady job for the last several years that pays well enough for my needs. There won’t be any private islands being purchased in my near future, but I have the bottom couple levels of Maslow’s pyramid taken care of so I won’t complain.

Even so, I still spent too much in 20111, and so 2012 must be the year of less spending and more saving. Fewer trips to restaurants and more usage of what’s in the pantry. Fewer purchases of stuff that isn’t really needed and more donation of stuff that doesn’t get used. Less reliance on consumerism in the middle of the worst recession this country’s had since the Depression, and more enjoyment of the simpler pleasures that life offers… for free.

Less unhealthy activity

America is fat. Over a third of our adult population is obese. We eat too much, we eat too poorly, and on average we don’t spend enough time balancing that out. So 2012 needs to be the year of less unhealthy activity – less junk food, less soda, and less lounging on the couch. More water, more trips to the gym and more walking or biking (when possible).

But 2012 also needs to be the year of less unhealthy mental activity. I spent too much of 2011 wallowing in my own head, bemoaning the sad state of me. That needs to stop.

More challenges

Lest all that seem too negative, here’s some positivity. The new year is the perfect opportunity to challenge yourself, to set goals to achieve. Not goals like “tomorrow I will (try to) get out of bed.” Challenges like “I will learn a new language” or “I will start that new business” or “I will finally take up fiery sword-swallowing”. Something we know will be difficult for you but that we can accomplish with enough effort. But it has to be difficult. It has to be outside our comfort zones, otherwise what’s the point?

Personally, I want to learn at least two new web coding languages – one front-end and one back-end. Maybe that doesn’t appeal to you. Fine. Find something that does, and go do it.

More exploring

I’m an introvert. My shell is thick and well-weathered, and I stay inside it as much as possible. Being around people is physically exhausting2. This is obviously not conducive to leading a life of adventure.

Most of my life has been spent in Milwaukee, but most of it is still foreign to me. I’d like to change this and really see the world around me. More travel, more exploring outside of the city, outside the state, and most importantly out of the comfort zone. We could probably all do with some exploring of the terrain outside our cozy little shells, no matter how cozy those shells might be.


2012 needs to be the year we collectively get our dren together. Less time spent doing ourselves harm and more time spent doing ourselves and others good. We’re better than we think we are, we just need to convince ourselves of that.

  1. To be fair, my trip to SXSW in March accounted for a pretty big chunk of change that won’t be repeated anytime soon.
  2. I totally want a squirt gun of justice. But it would have to be one of the big, highly-pressurized cannon-style guns. A puny little kids’ toy isn’t sufficient for my needs.

Round-up: Accessibility References for Non-Tech People

Elizabeth Galle tweeted a request today for accessibility references that a team of not-necessarily tech savvy people would get some use out of. Twitter responded with some great links almost immediately, and I wanted to collect those replies here in one place to serve as a starting point for any others with similar needs.

The tweet that started it off:

@Tawreh makes an excellent point that web accessibility can be likened to a book, and that you should give your readers a sense of “I know where things are” immediately rather than trying to reinvent the wheel and inevitably confusing them (or frustrating them to the point that they just give up).

Others presented links to basic guidelines from the W3C and WebAIM groups, the authoritative sources for web usability and accessibility. Continue reading “Round-up: Accessibility References for Non-Tech People”


Your House is Burning – What Do You Grab?

A thought experiment, if you would. Your house is burning. What do you take with you? Let’s assume for the sake of discussion:

  • You wake up in your bed and realize there’s a fire you can’t put out; you need to get out.
  • You have a safe exit, but not for long.
  • You have some kind of small bag handy, like a backpack or a pillowcase, that you can throw stuff into.
  • You can only make one trip. Once you’re out, you’re out; no going back in for more.

What do you grab? Continue reading “Your House is Burning – What Do You Grab?”