Let’s talk about Sphinx

I’ve fielded a few questions lately from folks about Sphinx, reStructuredText, and documentation in the Python world and more broadly. So I thought I’d write up a bit of an intro to how I use and understand these tools, and how better documentation makes me a better developer. Restructured understanding of reStructuredText There’s a lot …

Defense against the Dark Arts

I’ve just been reading Carole Cadwalladr’s excellent journalism on the subject of Robert Mercer, Cambridge Analytica, and the Brexit and Trump votes. You can see the articles here and here. They’re chilling, and upsetting, and important. At some level, what Cambridge Analytica is doing is something familiar: propaganda. It’s different in two respects, though: one, …

Great American Institutions

This country likes to talk at length about how much it values democracy, as a core concept. For a long time, I’ve said that this strikes me as strange, when two out of three of our major cultural institutions are (mostly) based around (substantial) autocracy. That is, while we pursue democratic government, we maintain autocratic …

The End of the Third Age

I’m going to talk about the Lord of the Rings. Or maybe America, at this juncture in time. Tolkien, famously, hated allegory and rejected allegorical interpretations of his work. And yet, time and time again, people have found an allegorical reading of his Lord of the Rings inevitable and tempting. There are plenty of reads …

South Pacific

I grew up listening to a lot of Rodgers and Hammerstein; it was some of my mother’s favorite music, and so there was a lot of it in the house. More than any other musical of theirs, I listened to South Pacific. Now, there are problems, of course, with that show. It’s a product of …

Craft and writing prose

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 …

Programmers aren’t special

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 …

Embellish later

So, @wholemilk said something I liked: Note to self re complicated programming: EMBELLISH LATER. — the no woman (@wholemilk) January 29, 2016 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 …

Teamwork and Crosswords

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 …

Code Folding

Nick made a comment about code folding, and I promised him an essay. Here it is. It’s not very long. I like code folding. When I know a mature project well, and the modules are kinda big, I want to open a file and not be distracted by seeing things I’m not working on. I …