Why documentation is the broccoli of programming—and life

On code, truth, and the penance of writing things down

In my day job, I do a lot of programming. That’s one of the fun parts. The not-so-entertaining part? Documentation. I’ve told my teammates, “You’ve got to pay your penance”—meaning you don’t just write code, you document it too. If you designed something overly complicated, your penance is the extra time it’ll take to explain it.

The Code Never Lies

Documentation has its own set of problems:

• It’s usually done last, so it’s first on the chopping block when deadlines loom.

• If you do it early, you’ll probably have to redo it as things change.

• You never know how much someone will read it, so spending too much time might feel like a waste.

• It’s often inadequate, and you don’t know how much faith to put in someone else’s notes.

At work, we say, “The code never lies—but the documentation might.” Code reflects reality. Documentation might reflect a hopeful version of reality, or a past one.

Emily the Note booker

There's a bit of an irony that what is penance to me is one of my daughter Emily's roles on her robotics team. She is the note booker whose job is to create an engineering notebook that documents the design process.

Fake It Till You Make It

Back in middle school, her team came up with a robot design and just built it. Judges like to see a decision matrix in the engineering notebook: what options were considered, how they were weighed, and why the final design was chosen. Her team didn’t really do that. They just built the robot, then retroactively invented a matrix to justify it.

I told Emily, “You might’ve had a better robot if you’d actually done the matrix.” But it’s hard to push back against your team and suggest a new process.

Talking to Your Future Self

Sometimes, in programming, you revisit your own documentation. Maybe you wrote it five years ago—or five weeks ago—and you’re trying to remember what you did. If I find something helpful, I might say out loud, “Good job, old Dan.”

To Thy Own Self Be True

Documentation is a microcosm of life. We often try to cut corners to get to the finish line faster. It’s like eating your greens—you know it’s good for you, but that doesn’t mean you want to do it.

If you lie in documentation (like Emily’s team did), you’re probably not going to be as good as you could’ve been. That’s life. “To thy own self be true.” Would you believe I made that up myself? Lol. No, that wouldn’t be true.

One of my core values is seeking truth. If you’re not truthful with yourself, you’ll never live up to your full potential. Don’t get me wrong—my gut reaction to being told I’m wrong might be anger, hurt, or denial. But after time to contemplate and debate, I find my way to what I believe is right. That’s probably why I play devil’s advocate sometimes. If you can argue the other side and convince yourself, maybe it’s worth reconsidering.

Documenting the Past

Years ago, a few years after my dad died, I had an idea. I wanted to learn more about my parents’ lives and document our family history. I proposed that my brothers and I send my mom one question a week by email. She could respond at her own pace. It would be simple, and it would create a written record.

She flat-out rejected the idea. She didn’t see the point, and she felt the memories might be too painful. I understood, but I was disappointed.

Help Me Remember

Now, years later, I see another reason for documentation. I ask myself: if I develop Alzheimer’s someday, what might I wish I’d done when I was younger? That brings me back to documentation. I might want to remember the past—and who better to tell me than my younger self?

Time to Pay My Penance

For years, I’ve been mute on social media and email. Email is for work. Facebook is for the occasional birthday wish or proud parent moment. But if in thirty years I want to say, “Good job, old Dan,” then it’s time to start paying my penance.