Make code better by writing about it
Writing improves thoughts and ideas. Doubly so for thoughts and ideas about code.
Writing, about software or otherwise, is a process wherein:
- thoughts and ideas are clarified
- ideas are transferred to colleagues
- culture (of a sort) is created by highlighting what’s essential and omitting what’s transient
Documenting code, as a form of writing, is a process wherein:
- the concepts and mechanics in the code are clarified
- what’s in our head today is made available to our teams (and ourselves) in the future
- culture happens by highlighting what’s intended and what’s “off the beaten path” when working with this codebase
I suspect that open source is (often) of higher quality than bespoke, proprietary software because it has to go through the crucible of documentation. Essentially, there’s a whole other design activity you have to go through when publishing a library or framework that internal/bespoke software does not.
I can’t objectively verify this. Subjectively, when I have made the time to write words about a bit of code I wrote, it has resulted in improving the design of the code along the way. Or, I better understand how I might design the code in the future.
Writing is a great tool for designing code. Use it more often!
Corporate personhood and ants
Filtered for ants and laws, Matt Webb:
Let’s say we could chat with ants. Could we trade with them? What would we want from them?
…
In short: people treat almost everything as people, at least a bit, including companies.
- We could try to communicate with ants and then include them in capitalism. Would this raise all boats for humans (who currently do low-paying/low-prestige work) and the ants (what is good pay/prestige/standard of living for an ant, I don’t know!)?
- We attribute person-like qualities to corporations. Infamously, in the case of Citizens United and more innocuously like attributing creativity to Apple, potential then hucksterism with Tesla, or declining design aesthetic with BMW.
- If we bring ants into corporatism and personify them, there’s an opportunity for some futurist/dystopian sci-fi where a mysterious cadre of house cleaners/chore-doers conceal themselves via surveillance technology and financial engineering of shell corporations. Turns out, it’s just a mega-colony of ants.
Turn the pages. Read the code. Hear the words.
“Turn every page. Never assume anything. Turn every goddamned page.” — Robert Caro, Working
So goes the wisdom super-biographer Robert Caro received from a mentor when he was an investigative reporter in New York. Caro went on to apply this energy and depth to write a sprawling biography on real estate developer Robert Moses and four volumes on the life of LBJ.
I like the energy, determination, and purpose of Caro’s advice. In his writing, Caro takes a maximalist1 perspective2. He looks to understand the system. Caro read every original document in every archive he could find (“turning the pages”) to ensure he fully grasped the context of historical events and didn't miss any details that might change the interpretation of events. Caro tries to load the whole state of his subject into his head and notes. Only then does he start writing his expansive biographies.
1. Read the code
Building software benefits from the same energy and determination displayed by Caro. As I’m working on a project, I flip between code I’m writing, code I’m using, and adjacent systems. Once I’ve read enough to have the problem and system in my head, I can move through the system and answer questions about it with that everything is at my fingertips feeling3. Fantastic.
Recommended: read third-party libraries, frameworks, standard/core/prelude libraries. Read demo code. Find inspiration, learn something new, and build the muscle for reading code with confidence.
2. Hear the words
When I’m really listening, avoiding the urge to think through what I’ll say next, I’m doing my best work as a coach or mentor. When I really hear and understand what a colleague is trying to accomplish or solve, it’s a bigger win for everyone.
Subsequently, I can switch to brainstorm or solution mode. Not before.
Recommended: literally listen to what they’re saying. Especially for the leaders and managers out there. Get the context needed to understand what they’re thinking. Ask clarifying questions until you’re sure they understand what they’re thinking. Don’t start responding until you’re sure you understand the context and the kind of response4 expected of you.
3. Build a model
Reading (words and code) and listening are great ways to build a mental model of how an organization, system, team, or project works. That said, a model is mostly predictions, not rules or hard-won truths.
To verify your model, you have to get hands-on at some point. A model is likely invalid unless it’s been applied hands-on to the system in question. Make a change, propose an updated process. See what happens, what breaks, who pushes back. Building (with code, with words) upon the model will evolve your understanding and predictions in ways that further reading or listening will not.
Recommended: turn reading words, reading code, and listening into a model of how your code-base, team, or organization work together. Apply that model to a problem you’re facing and use the results to improve your predictions on what actions will produce welcome outcomes. Rinse and repeat.
4. Go forth and deeply understand a system
With due credit to Robert Caro, I suggest doing more than “turning the pages”:
“Read the code. Read every damn function or module you’re curious about.” — me, a few months ago
"Listen to what they're saying. Hear every damn word until they're done talking." — me, several weeks ago
Next time you think “I need more context here” or “that seems like magical code/thinking”, go deeper. Take 15 minutes to read the code, or listen 15 seconds longer to your conversation-mate.
Turn the pages. Read the code. Hear the words.
- Aside from his biography quote above, all of his books are doorstoppers. ↩
- Extensively aided, it should be noted, by further research and organization by his wife. ↩
- Aka Fingerspitzengefühl ↩
- e.g. commiserating, brainstorming, un-blocking, taking action, etc. ↩
Remote work skills today look like being online in my youth
Checking my emails frequently. Responding to a few group/direct-message chats at a time. Managing to write code, do math, or put together a slideshow/essay at the same time. Always in front of a computer.
That’s what productivity in my college years1 looked like. There was lots of multitasking and goofing around online. A smidge of collaboration via nascent networks2.
There is little coincidence that’s close to how I work today. Slack is a better IRC3, messaging apps work a lot like AIM4 and ICQ5 did back in the day. I try to focus more and multitask less, to the extent that circumstances and discipline allow.
What strikes me is, when my career started6, that’s not how we worked.
In the early 2000s, if I needed to talk to more-experienced developers or managers, I wrote an email or walked over to their office/cubicle7 to try and catch them for a quick chat. If I needed to talk to a more junior developer who was just out of college (like me), I sent them an instant message. I probably had Slashdot, IRC, or several blogs open in a minimized window somewhere.
Now, I’m the experienced developer/manager-type person, and the style of work matches a lot of my college habits. A lot of that is leadership determinism (i.e., I have the agency to set and model the structure of our work). Maybe some is down to measurable productivity improvements that, e.g., Slack bring. Most of it feels like it is down to the opportunity seized of remote work – you can’t work remotely without all the tools folks in my cohort started using as we were pivoting from students to professionals.
Today, “Extremely online” is a whole other thing that is unrelated to how I work professionally. But as a new generation becomes the largest in the workforce, probably that will change and things will look a little weird to me. So it goes!
- 1998-2003. Most of those spent on a dual-everything Linux PC. I bought my first laptop/Mac in December 2002. ↩
- Mostly, folks were Very Offline. Especially outside my generation, but even in my peer group. Now, we’re all Pretty Dang Online. ↩
- For all but the neck-beard-est measurable axes. ↩
- AOL Instant Messenger, the definitive software of my youth. ↩
- Which required knowing your user ID to get people to add you as a friend. Thusly, I can still tell you my ID to this day: 11772935. ↩
- Roughly 2000 is when I did my first productive programming for money. ↩
- Thinking back, cubicles were not great or cool, but they did beat desks in an open layout on most axes. Larger pair cubicles with someone you like to collaborate with were pretty good, all things considered. ↩
Songs You Must Listen To At Maximum Safest Volume
- “Uptight”, Steve Wonder
- “Summertime Blues”, The Who
- “Wouldn’t It Be Nice”, The Beach Boys
- “Good Vibrations”, The Beach Boys
- “Jungleland”, Bruce Springsteen
- “Once In a Lifetime”, The Talking Heads
- “Flashlight”, Parliament
- “Rhythm Nation”, Janet Jackson
Top of Mind No. 3
Working in small increments towards medium-to-large projects or outcomes is tricky. I too frequently find myself down a much deeper rabbit hole than I’d intended. And I’ve spent a lot of time thinking about it and practicing at it! Recommended reading: Simon Willison on productivity.
Read-only and write-only modes of accessing social media – there’s something good here. E.g., blogs and feed readers are distinct from most1 posting software. Currently, I’m reading Twitter once a day, as a digest, without the ability to scroll an infinite timeline. If I want to post, I open up an entirely different app that nudges me towards writing instead of dashing off hot-takes. Interestingly, Typefully and Mailbrew are what I’m using for this and are made by the same team. I wonder if that was intentional or a happy accident?
Billing/subscriptions/payment projects are absolutely crucial, “undifferentiated heavy lifting”, and difficult to pull off. I have a ton of unstructured ideas about this. The latest kernel of an idea: billing projects are very likely to involve weird interactions between business goals, customer psychology, and anecdata.
The nap hierarchy – naps are probably in my top 5 list of work-from-home benefits.
- Early versions of NetNewsWire and Userland Radio notwithstanding. ↩
Albums You Should Listen To From Start To Finish
- Born to Run, Bruce Springsteen
- Blood Sugar Sex Magik, Red Hot Chili Peppers
- Pet Sounds, The Beach Boys
- The Blueprint, Jay-Z
- Songs in the Key of Life, Stevie Wonder
- Sign ‘O The Times, Prince
- Symphony No. 9, Beethoven
- The Rite of Spring, Stravinsky
The nap hierarchy
Doing a short snooze in the middle of the day? I highly recommend it if you have the means. Ideally, one of these places (in order by quality of rest):
- Couch nap
- Chair nap (recliner/lounge chair, ideally)
- Bed nap
- Sky nap (airplane)
- Train nap
- Car nap
Places I have napped, for better or worse, and would not recommend:
- A rock concert (The Who, Bruce Springsteen)
- A college lecture
- A piano recital
- Voyage of the Little Mermaid (Walt Disney World, Hollywood Studios)
- Great Moments with Mr. Lincoln (Disneyland)
- American Adventure (Walt Disney World, EPCOT)
Bruce Springsteen Epochs
- Motown Bohemian, curly hair, The Wild, The Innocent, and the E-Street Shuffle
- Denim, muscles, Born in the USA
- The introspective wanderer, bolo tie, Human Touch
- Revival, the flavor-saver goatee, The Rising
- The rock ‘n roll stateman, dark vest and necktie, High Hopes
What A Guitar Is Supposed To Sound Like
- “Summertime Blues”, The Who, Pete Townsend
- “Estranged”, Guns ‘n Roses, Slash
- “Glory Days”, Bruce Springsteen and the E-Street Band
- “Highway to Hell”, AC/DC, Angus Young
Music I Wish I Had Written
- The Rite of Spring, Igor Stravinsky
- The Planets, Gustav Holst
- “Good Vibrations”, Brian Wilson
- “Losing My Edge”, James Murphy
- “I Feel the Earth Move”, Carole King
Best of 2022
Television: Severance (Apple TV), Andor (Disney+)
Movie: Everything Everywhere All At Once
Music: deep dives into Carly Simon, Nina Simone, J Dilla
Book: Player Piano by Kurt Vonnegut
Blog: Pain Don’t Hurt (a 365 day series of short essays on Roadhouse)
By my calculations, I managed to write about fifty pages between my blogs this year. That’s about double what I wrote in 2021, so I’m pretty happy with where I ended up here! 💪
My best writing this year, in my opinion:
Classical music that is terribly edited in commercials
- “Also Sprach Zarathustra”, Richard Strauss, the opening
- “Symphony No. 6”, Beethoven
- the rest of the Western classical music canon
Think your thoughts
We live in the most amazing time for ideas. They’re all over the place. It’s never been easier to share them, and indeed they are shared at a phenomenal pace1.
It’s so easy to find ideas that it’s a little difficult to squeeze our ideas into the noise. Plenty of folks will tell you how to “build an audience”, but I want to make it personal.
Build an audience with yourself!
Make room for your thoughts to exist in your head despite all the noise that exists in our modern world.
1. Clear mornings
I’m a morning person. I do my best work early in the day. Look at my calendar, you’ll see this. One giant, defensive block to focus in the morning and get stuff done. Please — do not schedule me in the morning2!
However, I’ve come to think there’s more to a good morning than a clear schedule. Having a clear mind, with stillness and lack of lingering stressors, helps a lot! If I wake up with something bouncing around in my head, seize it or solve it. Write it down to think it through or solve tension3 my brain has dwelled on overnight.
Going deeper into a clear mind reveals the absence of others. A truly spectacular morning of creativity correlates to (almost) exclusively thinking my thoughts. My ideas in my head4 — great! Someone else’s idea, via social media, television, books; promising, but likely not as good.
2. Attention machines
Among books, television, podcast, radio, etc., ideas via social media are particularly hard to avoid. I have to put a lot of discipline/energy into “don’t open socials, chats, emails, news, etc.” before 11:30am lest another idea trample over my idea.
Modern social media has evolved, in form and function, to bypass the smart part of our brains and go straight for the emotional and often irrational part. It’s the upsetting and frustrating ideas that stick with me when I use social media. Rarely do I open my laptop, read social media for a few minutes until a good idea comes up, and then close the laptop to go think about it.
The doom-scroll demands more scroll.
The upside is, we may also live in a moment where the abundance of ideas surfaced by attention machines comes into balance as alternatives to hyper-scaled social networks come into play. I’m hopeful that to a smaller extent, Robin Sloan’s words on de-leveraging from Twitter will start to ring true as Twitter, in particular, fades from prominence:
The speed with which Twitter recedes in your mind will shock you. Like a demon from a folktale, the kind that only gains power when you invite it into your home, the platform melts like mist when that invitation is rescinded.
3. No retreat
The previous is not to imply that attention machines aren’t useful! I don’t want to Waldenpond or go full digital luddite. When I squint at it with optimism, some forms of social media look like a networked/distributed system attempting to reach a consensus5.
There are less intense attention machines that aren’t built around hyper-tuned engagement loops. Basically anything where I have a list of things to watch/read/enjoy is an attention machine: a Netflix watch list, YouTube subscriptions, Substack subscriptions, and the humble/old RSS reader. These don’t demand that I stay in a loop, thinking other people’s thoughts and consuming the surrounding ads. Which is useful because I want to get other people’s thoughts, but only on my terms.
I find that my thoughts are more interesting if I prime them with idea from specific authors via various primary sources, social networks and otherwise. It’s thrilling to discover new scenes, folks self-organizing into web-rings and networks and chats to think about or share the commonality and challenge of their work or hobby. Having that kind of energy bouncing around in my head tends to improve my ideas rather than dilute them like hyper-scaled social networks might.
Bottom line: keep using the web to find fascinating people and scenes, participate in a few of them.
4. Seize your thoughts
I return to A Precious Hour from Rands in Repose, a lot:
Each day I blocked off a precious hour to build something.
Every day. One hour. No matter what.
Every day? Yup. Including weekends.
An hour? Yup, 60 full minutes. More if I can afford it.
Doing what? The definition of “building a thing” is loose. All I know is that I get rid of my to-do list, I tuck the iPhone safely away, and if there is a door, I close it. Whether it’s an hour of Choose yourownadventure Wikipedia research, an intense writing session, or endlessly tinkering with the typography on the site, it’s an hour well spent.
Make the most of the mornings (afternoons, evenings, whenever it is for you). Work the thoughts I find compelling, not merely upsetting or prevalent. Share it with interesting people. That’s how an exciting life of thinking my own ideas happens6.
- For better or worse! 😬🤷 ↩
- This is as much a message to myself as anyone else. Too many times I’ve scheduled an appointment in the morning thinking “surely it will be fine this time” and surely enough current-me regrets the decisions of past-me. ↩
- Usually: think it through by writing it down. ↩
- What a concept! ↩
- See also: Graph Minds. ↩
- I think! ↩
Driverless Crocodile, Nostalgia Revisited:
Nostalgia: a kind of homesickness for the past.
Another way of putting it: the longing you will have in future for the places and people around you now.
Time’s arrow is a hell of a thing.
Top of Mind No. 2
How I work: what might “pairing” with a language model-based assistant (e.g. GPT-3) look like?
How I build: the tension between the web platform being more capable than ever versus the difficulty of standing up many kinds of “basic” applications. e.g. animation is better/more sophisticated than ever, but skipping ahead with building web/database applications requires expertise and a few hours to get something up and running.
How I collaborate: encouraging teams to work in issue threads, thereby improving the quality of thinking (via writing) and building ambient, asynchronous awareness amongst teammates.
An ideal weekend
Nothing, nothing, nothing makеs me happy
Nothing brings me nothing but joy
So if you haven’t tried nada
I really think you oughta
— C. Fischoeder, Bob’s Burgers
On minor funks, needing a reset, and indeed doing nothing.
The Reset. Occasionally, the things I do stop doing it for me. Games, shows, books, magazines, etc. I pick them up and realize I’m bored with all of them. I require a break from my breaks.
Oddly enough, taking a vacation or extended weekend with too little purpose or purpose too close to routine seems to generate the same response.
The Reset almost always involves going offline, to some extent. Not like Craig Mod hiking through rural Japan1. It sometimes involves catching up on chores, tidying up the house, or extremely low-key home improvement2.
Related: YouTube could use a function for this. “All my subscriptions & recommendations aren’t doing it, we need to go weirder/normal-er”.
Doing absolutely nothing is an option, but ends up feeling a little more hollow than free-ing.
More often, rebelling against my routines and script-following tendencies works. Binge-watching, grinding a game, ignoring diet, etc. sometimes get me clear.
The trickiest bit is when I’m in An Indefinite Funk. Hobbies seem shallow or meant to impress others or not fulfilling anymore or too much like work or too expensive/intensive to maintain.
So far, I don’t have a great antidote for that. Last time it happened to me, I reverted two decades to making music, decided it still wasn’t for me, and went back to enjoying and sometimes studying/pontificating on music.
Going offline is in some ways a luxurious and nice way to reset. We so rarely allow ourselves a moment or location of offline-ness. If you have to book a flight or outfit your Porsche 911 for camping, so be it. It’s fine to just put your online devices in another room, too.
Recommended: do yourself an Ideal Weekend 3:
- Get coffee
- Go for a walk in a nice park
- Take a nap
- Read a book
- Go for a swim
- Stroll through the vibrant part of your town
Any weekend that includes most of those is likely to give me a reset such that any funk that is imminent or currently occurring goes away.
One thing at a time, incrementally
Only Solve One New Problem At A Time, Ben Nadel:
The example he gives in the episode is "learning Golang". Understanding how to use Golang was a new problem for the company. As such, in order to start integrating Golang into their work, they applied it in the context of an already-solved problem: sending emails. This way, Golang was the "one thing" they were solving—the email-sending logic already existed in Ruby; and, they just had to port it over to a new application server.
Good advice for any developer at any experience level1!
The ability to focus on one concern at a time is possibly the mark of a senior developer. It takes experience to ignore other factors as noise. It takes time to learn how to avoid tripping on distractions/side-quests. Distinguishing useful, new information from distraction and noise is the mark of a focused senior developer.
The trick for juniors, is they’re always learning more than one thing at a time, often on accident. They want to build a feature, but it requires a new library, and it requires learning the library. They went to start up my development server, but then something weird happens with Unix. It's the essential challenge of being a junior – they’re just getting started, so they’re always learning a couple of things at a time2.
If I could be so bold as to add a corollary to the rule of "one new problem at a time", I'd suggest that if it can't be done incrementally, don't do it. Over the last 6-years, feature flags have revolutionized the way that I work. And, a majority-stake in that change is the fact that everything I do is now built and integrated incrementally. Until you've worked this way, it's hard to even articulate why this is so powerful. But, I literally can't imagine building anything of any significance without an incremental path forward.
Working incrementally: absolutely, more people should do this. Even seniors. Especially myself!
Now, the tables can turn. I’ve observed juniors who are more adept at working incrementally than seniors. Because they’re tripping over other tasks all the time, the junior has to work in smaller increments to make progress.
Perversely, a senior who can see the whole feature/change in their head is sometimes tempted to push the whole thing through in one (large) change. Developers who have learned3 to avoid pitfalls and gotchas sometimes have to relearn how to work incrementally.
I speak from experience! Working incrementally is something I consciously have to work towards. Conjuring a masterpiece into existence in a fury of git pushes and one pristine pull request feels good. On net, a big bang of development is a detriment to my team. An early pull request, small tactical commits, and a write-up to describe why and how I got there are more useful to align the team and spread ideas.
Previously: one priority is like wind in the sails.
- I’m looking a this sentence again, double checking it, and yes this is a global pronouncement about programming and developers and yes I think it carries its weight↩
- Or even worse, accidentally learning things that aren’t relevant to what they’re trying to tackle. Sometime, ask me how excited I was about Tcl/Tk in 1998, arguably several years past the apex of that language/toolkit. ↩
- Often through the luck/privilege of having lots of time to practice/tinker at programming outside the job! ↩
How I would explain music to an alien
Were I faced with an intelligence not of this earth, but one that shares our understanding of what music is/for, these are the exemplars I would hold up for them to understand our cultures through my favorites:
- Hip-hop: “So whatcha want”, The Beastie Boys
- Rock and roll: “Highway to Hell”, AC/DC
- Symphonies: “Symphony No. 7”, Beethoven
- Pop: “Walkin' on Sunshine”, Katrina and the Waves
- Jazz: “Giant Steps”, John Coltrane
- Funk: “Mothership Connection”, Parliament