It ain’t sexy, but it’s critical

Evacuated Highway 401 Color.jpg
(Photo credit: By Kenny Louie, CC BY 2.0,

Think, for a moment, about things that are never talked about — I don’t mean taboo topics, but rather, things that are boring, “ain’t sexy,” and so on — yet are absolutely critical if we want to maintain or move ahead our current standing. Off the top of my head, infrastructure and chores come to mind. Road construction, transportation infrastructure, and public utilities aren’t exactly exciting topics that are discussed over drinks, but maintaining them is absolutely critical if we want to keep our society moving. Likewise, nobody talks about housework, taking out the trash, fixing leaks, replacing appliances, and so forth, but it’s necessary if you want to maintain your home.

Documentation falls under this category. Let’s face it: the large majority of developers, analysts, and other business and technical professionals don’t enjoy writing documentation. Raise your hand if you’re passionate about documentation. (You, yes you, the technical writer in the back row, put your hand down. I’ll get to you in a moment.) But the fact is, documentation is absolutely critical if you want to keep your business afloat.

I was thinking about this not long ago, when I was describing aspects of my job to someone. I’m currently working on an important documentation project (a standard operating procedure document — SOP, for short), and I’ll admit that it isn’t the most exciting project. It isn’t unusual for me to zone out in the afternoon while I’m working on this thing. I was asked, is it an issue with your department or your company? I said no. It’s the nature of the beast. It would be like this regardless of where it was, whether it was with my current team, my current employer, or somewhere else.

No, working on the document is not exciting work. But it’s an important document that needs to be written. It’s a job that (almost) nobody wants. But it’s also a skill that I’m good at doing (or at least I like to think that I am). And it keeps me employed.

I’ve written before that documentation is one of the most disrespected technical tasks. But it’s a critical task if you want your business to stay afloat. You need to be able to pass information along to your colleagues, your employees, and your clients. Documentation is probably the best way to do it. So documentation needs to be clear, understandable, well-written, and presentable.

This is why I preach what I do at SQL Saturday. You ignore documentation at your own risk. No, documentation ain’t sexy. But it’s absolutely critical if you want to keep your business going.