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:

  1. thoughts and ideas are clarified
  2. ideas are transferred to colleagues
  3. 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:

  1. the concepts and mechanics in the code are clarified
  2. what’s in our head today is made available to our teams (and ourselves) in the future
  3. 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!

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.

  1. Aside from his biography quote above, all of his books are doorstoppers.
  2. Extensively aided, it should be noted, by further research and organization by his wife.
  3. Aka Fingerspitzengefühl
  4. 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!

  1. 1998-2003. Most of those spent on a dual-everything Linux PC. I bought my first laptop/Mac in December 2002.
  2. Mostly, folks were Very Offline. Especially outside my generation, but even in my peer group. Now, we’re all Pretty Dang Online.
  3. For all but the neck-beard-est measurable axes.
  4. AOL Instant Messenger, the definitive software of my youth.
  5. 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.
  6. Roughly 2000 is when I did my first productive programming for money.
  7. 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.

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.

  1. Early versions of NetNewsWire and Userland Radio notwithstanding.