I work on ways to write programs that convey their big picture to the people who run them. The goal: use an open-source program, get an idea for a simple tweak, open it up, orient yourself, and make the change you visualized -- all in a single afternoon.

Conveying global structure is subtly different from making code ‘readable’. The conventional ideal of readability tends to focus on helping authors evolve programs rather than helping outsiders live within them. Formatting rules and procedures for submitting patches don't help newcomers early on, when they need the most help.

Understanding a strange codebase is hard. I can't change that, but I think I can make it easier for people to persevere. I want to carve steps into the wall of the learning process. Most programs today yield insight only after days or weeks of unrewarded effort. I want an hour of reward for an hour (or three) of effort. To get it, I think programs must:

• …tell the truth about their side effects. People naturally try out programs to understand their use. An untrusted program must inspire confidence that it can be run without causing damage.
• …provide value. People need to organically see usefulness before gradually caring about internals.
• …come with source code. Conventional packaging approaches tend to discourage curiosity.
• …build easy from source code. In particular, each build requirement magnifies the risk of a failed build on somebody's computer.
• …emphasize minimalism over polish. Focus on core functionality out of the box, rely on people to tweak programs for uncommon needs and contexts.
• …support ill-considered changes. Provide immediate feedback, explain why a change is bad.

I focus on conveying global structure to outsiders because it lies on the path to many seemingly-unrelated problems, and simplifies many seemingly-intractable problems:

• Complex programs are disproportionately unlikely to work well. Focusing on outsiders forces simplicity.
• Software today is overwhelmingly exposed to malicious outsiders. Encouraging people to peek under the hood shines sunlight on dark corners.
• Software supply chains today are easy to subvert to smuggle malicious code into people's computers. Keeping the build simple keeps the supply chain short.
• Software today often feels sluggish. An ethos of self-sufficiency keeps overheads from compounding.
• Software today is often shepherded by large teams. People have to be paid, their output managed. Their incentives have surprising consequences and create thorny problems. Things move fast for a time but then ossify. Keeping things simple can sidestep these social overheads, keeping the eco-system more supple in the long term.
• A big cause of complex software is compatibility and the requirement to support old features forever. Complex programs that discourage peeking inside force programs to support old and ill-considered changes. Complexity breeds complexity. Compatibility becomes more negotiable if people have the skills to work around incompatibilities. If we can take features out, programs aren't forced to grow monotonically more complex over time.
• More widespread understanding allows society to more naturally organize along shared desires. Communities that require more than a program provides can sustainably fork it. Changes don't have to go to everyone to provide use to some people. The eco-system becomes more resilient, the blast radius of vulnerabilities (and incompatibilities!) goes down.
• Encoding the reasons for old choices makes it easier for communities to confidently delete code irrelevant to them, further combating complexity and spreading resilience.

If the world I'm describing seems different and alien, that is deliberate. Software permeates the world, and its problems are inextricably tied to our social arrangements. We can't fix it in isolation. We have to find ways to coevolve with the programs that augment our selves. Follow my attempt to get there with my current project, Teliva.

Last updated Dec 26, 2021

Comments gratefully appreciated. Please send them to me by any method of your choice and I'll include them here.