Image 01


beyond the Kuiper Belt, over the sea

Archive for March, 2016

Craft and writing prose

Monday, March 28th, 2016

Prose is important; even if you’re writing for no one else, you’re writing for yourself in the future. The best developers I know write a lot of prose, both documentation and commit messages and comments. The value is not immediately visible, it won’t make your tests pass, but it actually is part of keeping technical debt low; some tech debt comes from not knowing in detail what a piece of code does. Good docs and comments and commit messages let you know at least what it’s supposed to do.

So, prose is a part of the craft of software development, but not just any prose: particularly technical prose, explanatory, lucid prose. And it’s not something we, as developers, are usually taught.

We’re, generally speaking, a group that’s pretty good at self-education, though. We pick up new languages, frameworks, protocols, and principles. So not only must we do this, but we can do this. It’s hard, because it’s big and fuzzy (there are no tests that can tell you if your prose is correct), but still, we can do it.

This post is just an exhortation, not a guide, though. The subject is too large to cover with a simple trick or a general principle. So, how do you begin to write better? First, write more and read more. Second, get your stuff edited.

Thanks to Ryan and Owen.

Programmers aren’t special

Monday, March 21st, 2016

Listen to craftspeople of all sorts. Learn from outside the bubble. We are not magical. What we do is not magical. It has some cool properties, so do other things. Learn.

(Yes, this means learn about how writers write. Yes, this means learn about how carpenters carpent. How psychologists psychologize. How baristas bar. How sailors sail. All of it.)

Embellish later

Monday, March 14th, 2016

So, @wholemilk said something I liked:

Yeah. But sometimes that’s hard. Why?

I am a big believer in the value of considering the emotional landscape of any labor, but in my day to day, that means mostly programming.

When you have something that’s working but still incomplete, it can be a big emotional effort to break it so you can start to move it towards the next stable point, the next point at which it’s working(-but-incomplete).

It’s like editing a document: partway through applying edits, you have broken sentences lying around, half-formed ideas not fully explicated, and the thing’s a mess. Sometimes that even shows through, if you fail to clean up after a change to the first half of a sentence leaves the last half incoherent.

It is similar with code.

Fundamentally, this is why source control matters. It is a tool to help with the emotional labor of breaking your work. If you know you can always go back to a stable point, swinging out into the void for a bit becomes exploratory, not all-or-nothing.

Teamwork and Crosswords

Monday, March 7th, 2016

Allie and I have been doing a lot of crosswords lately. While half the fun is yelling at Will Shortz when a clue is weak, the other half is in working together to solve a problem. And in the process, I’ve noticed something I find interesting. Teamwork can be about unlocking each others’ potential.

In this particular case, we had just done a Thursday crossword in record time, and I congratulated Allie on a job well done together. She countered that I had done three-quarters of the puzzle, and that she didn’t feel like she’d contributed her fair share. I however, felt that she had been crucial, and I realized it was because if she hadn’t been there doing this crossword with me, I would have been stuck at one-fifth and never completed it.

It was a very clear illustration to me of how teamwork, particularly in a complex creative task, is not about everyone doing the same amount of a generic and commoditized work, but rather about doing the right thing at the right time to help the team as a whole achieve more than the individuals would.

I’ve also been reading some pieces lately about Google’s Project Aristotle. It seems to come to a similar lesson, but in more concrete terms: a group’s effectiveness and intelligence is determined by the degree to which the members of the group can all contribute.

I think it’s worth remembering that effort and labor don’t just fill up a meter, and ding when it’s done. The complex web of human relations can make it hard to attribute success to any one piece of the system.