I registered for Out of Office Hours in July, then was invited to the August cohort, so I’ve been in the mentoring cohort for the last four months. I plan on mentoring there for as long as I’m useful - the commitment is so easy and I have an opportunity to have really uplifting conversations a few times a month.
I read this on recommendation from other people at Shopify. The concepts were good, and I highlighted several sentences, but the text was heavy with jargon.
A great and terrible catalog on the history of systematic racial oppression throughout the United States. Several examples were not far from where I read this and they hit close to home.
Another good reason to begin documenting your Theory of The Program: it’s a way to combat the death of the author. If you have explicitly written down the intentions of some software, and what it assumed, then others cannot add assumptions onto you in the future. You are also forced into honesty about what you initially considered and how you perceived the world. (From reading ferd.ca’s thoughts on language and inclusiveness)
Recently, I was reading Marc Booker’s post about the need for documentation outside of the codebase. A thoughtful comment on the post led me to Peter Naur’s paper on Programming as Theory Building, which I recommend reading1. In it, Naur argues that the act of programming is not a practice of writing code but the work of creating a theory of the problem at hand and a theory of the system to address it. As a team exercise, we practiced documenting our theories of the OfficeLuv system and found it very rewarding.
If you find it repetitive, I recommend skipping to the final couple pages where Naur talks about how best to actually apply “Theory Building” on your own. It comes after the actual paper. ↩︎
I would really love to see programmers/maintainers of influential libraries, frameworks, and languages (Redux, SwiftUI, Erlang, etc.) begin to describe their Theory Building as top-level documentation in the source code. I think several maintainers do good work to educate everyone with conference talks and blog posts (Rich Hickey, Dan Abramov, etc.), but documentation with the project would be amazing as an introduction with the codebase.
AppSignal asked me to write for their blog. My first post is about some techniques we’ve been using at OfficeLuv to responsively scale our queueing systems based on usage. From the introduction:
I picked up this book as it was recommended as a life-based and life-changing textbook on Hamming’s life at Bell Labs. I thoroughly enjoyed the stories sprinkled throughout but didn’t find as much value in the fully mathematical sections.
TLDR: email me at josh at joshbeckman.org
It is not enough to simply architect a system or solution. You must create a story, a path through it, from your current state to multiple end states. If you simply present a picture of end state, members do not know what to do to contribute. The path and the narrative is the actual useful solution. Architecture or solution alone is an empty vessel.
You can know what you are to do only if you also know what story you are a part of.
From reading Alasdair MacIntyre (via L.M. Sacasas).
Often, people who don’t have access to the raw data expect one narrative to be drawn from data analysis. But the analysts actually in the data know that there are always many, many narratives in the data. Data is opposite a single narrative. The narratives coming from the data are also never closed or complete, as data continuously arrives. But people want and attach themselves to a single narrative.