Programmer, Love Thyself

According to our Twitter bio, Postlight is a “digital product studio.” We’re also what you call a “client services” firm, which means we provide… I’m gonna say “services” to, uh… let’s call them “clients.” Rich and Paul are Postlight’s official brand ambassadors, so hit them up for clarification, but I’m pretty sure I’ve got this right.

To be honest, Postlight is my first legit engineering job working with a team; before I joined the company last year, my engineering experience involved me, by myself, hacking away on personal projects or writing software for coworkers who had no clue what I was doing short of the final product.

What that means is until recently, I’ve avoided learning many of the very valuable lessons most people learn as junior engineers. So, in the spirit of Gina’s guide to modern JavaScript for ancient web developers, I’m going to share one such lesson with engineers, ancient and modern, who like me have somehow come this far in their career having not learned.

Take my hand, and leave your shame behind, because what I’m about to say is ridiculous.

I Love Documentation!

I love documentation, and I don’t care who knows it! I’m not even that good at it. But I love it, and if you cared about yourself at all, so would you.

In the mid-2000s, when I was learning Ruby in my spare time with no previous programming experience, I was fascinated by the passionate debate programmers would engage in — really interesting and not at all exhausting debates about code styling, about which language was better than the one I was using, and concerning what framework was faster and cooler than the one I was using. “Programmers are smart!” I thought. “I’ll never understand all of this!”

I was right. Those debates are still happening, I still don’t understand many of the finer points, and I still find them fascinating. But there was one other thing that would occasionally crop up in a blog post that I didn’t understand until very recently: Odes to code documentation.

When you’ve only worked by yourself, the idea of documenting your code seems like a massive waste of time. Who exactly are you documenting for? Sure, if I worked at a client services firm, I’d totally document my code. You’ve got to build for that handoff! But I didn’t work for such a firm, so again, what’s the point?

Then I learned something anyone who’s fallen for their own README knows: documentation isn’t an act of altruism. Sometimes other people will benefit from your README, and if, incidentally, someone who isn’t you finds your docs useful, that’s really lovely. Bless their heart! But what every good programmer I know eventually comes to understand is that documentation is something you do for yourself—or rather, for future you.

It’s a lesson that should have been obvious years earlier, after the tenth time I had to relearn how to restart a Rails server on a VPS in the cloud somewhere, or reindex Sphinx, or, most infuriatingly, how to develop or deploy literally anything in a project. (I’m completely unable to touch one of my first large projects because I wouldn’t know where to start.) But since the only person I was accountable to was myself, and because apparently I carry some deep-seated self-hate into my work, I didn’t learn that lesson.

I’m happy to say that is no longer the case, and yes, it happened because I became accountable to other people. I had to appear as though I was a good digital citizen, so I made an effort to look like one. What I learned is that while other people rarely benefited from that effort, I would benefit constantly!

Now I document virtually all of my code, most of the time before it gets to GitHub. In fact, the smaller the project, the earlier I document it, since the less time I spend with the code, the less likely I’ll have a clue how to use it in a month. (This post was originally going to advocate for README Driven Development, a totally original idea of mine that no one else has ever thought of.)

The side benefit of documenting your code is that even though you just do it for you, it looks like you really care about helping other people understand your code, which is great. You don’t care about those people, but they think you do!

I’m not prescriptive about how and what you should document (though I’d love to hear people advocate for their favorite approaches in the comments). How do you run the thing? How can I use it once it’s running? How do you deploy it? Do you need to set up environment variables? Is there some sort of CI running?

The point is simple: Do any documentation and you’re inestimably better off than if you had not. And, in the end, isn’t this all about you?