You’ve seen it before: software projects with lucid and lovely documentation, all available on subdomain.readthedocs.org. So, how do? Well, the good folks at Read the Docs have made your life very easy. Assuming your documentation’s reStructuredText source is kept in git, and you are OK with pushing it to GitHub, you can get Read the …
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 …
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, …
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 …
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 …
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 …
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 …
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 …
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 …
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 …