When I first started my job, I had to set up a local version of our insanely complicated site, first on my work computer, then on my laptop, then on my home computer.
Our site is freaking huge. Setting up local versions of it is, to put it gently, a ginormous pain in the ass. Wrapping it, or versions of it, in a virtual environment helps. Sort of.
Once we got the setup sorted out, my then-boss said offhandedly, “You should write a blog post about that.”
I can’t remember a time when I’ve worked harder not to laugh. Let’s face it, laughing at your boss’s suggestion is not how most experts recommend starting out your new job. So I didn’t.
When I reported the conversation to a writer friend, she burst out laughing, too. If you don’t understand why it seemed funny, I’m not sure I can explain it. But I’ll try.
I think you have to have a particular conception of what it means to write. To me, writing about how to set up a virtual environment wasn’t material for a blog post – it was documentation. In part, that speaks to how I think about my blog. It’s my place to write, as opposed to code, or write about coding. That distinction is important, inasmuch as my job is mostly coding these days. It’s a “what I do in my free time must be fun” issue.
I realize a great many tech blogs consist of what I would consider documentation. And that’s a really, really good thing, because it’s great way to find human-friendly answers to difficult questions, or find other people who were just as frustrated as you at trying to do some technical thing.
Maybe what seemed funny to me is the idea that a writer would sit down and carefully craft metaphors around the topic of Python virtual environments – which you could! Technical documentation can be really well written. No argument there. You could, say, describe our virtual environment as a sandwich bag around our Ruby-Python-Postgres-Django sandwich. But I didn’t see myself doing that.
Frankly, I didn’t find virtual environment setup a particularly interesting thing to write about. Documenting steps is (for me) an unchallenging writing exercise. I’ve done a lot of it before, in various capacities. It’s something I would rather do at work. Whereas I enjoy my own writing as a way to think through difficult questions and abstract concepts, or perfect my joke construction technique, or work on my persuasive rhetoric, rather than as a means to express concrete information. And to that end, there’s also the academic in me, who needs to digest information and come a certain level of understanding before I write about something.
(“A male developer would never say that,” observes my friend who runs a program for women in engineering. She’s probably right.)
And then Garann Means posted on why more people need to blog about their coding, how frustrating it was to not find much diversity in the helpful documentation-type blogs I described above.
Hi. If you're a developer who doesn't tell anybody about their dev stuff, I wrote a blog post to you: http://t.co/PdAlUiP5Kr
— Garann Means (@garannm) September 12, 2013
Guilty as charged. And she’s got a point.
Though, while we’re being honest, I find it a pain in the ass to have to wrap things in
<code> tags while writing – as much as a pain in the ass, actually, as programmers find it to use a rich text editor. It’s ironically hilarious how opposed the two paradigms are, in my view, and there I go again: I actually have a huge blog post draft about that, about WYSIWGs and programmer culture and users and expectations. All the meta stuff. That’s what I like to write about, in general.
I still don’t think particular virtual environment of our office setup is an appropriate blog post topic. It’s too specific, and wouldn’t help anyone who didn’t work at our office. Though we have been trying to do a better job at documentation. Just yesterday we had to set a co-worker up with one of our apps, and we realized how horribly complicated we’d made it, so we simplified and documented it better. We’ve decided, collectively, to treat those horrible setup moments constructively, to reveal the tacit knowledge that we’ve been assuming. Little epiphanies, where we’re like, “Oh, yeah, we assumed the ten things we didn’t tell you! That wasn’t good! Quick, write the ten things down!”
So maybe I’ll blog about that. And code, too.