Abstraction: One from many

State of this note

As of Tuesday Jun 10 2025, this an unorganized thought-dump that needs to be edited.

I have this vague intuition that the heart of many practical CS and organizational problems is to minimize the distance between related pieces of information.

To make this very concrete: I think documentation should live as close as possible to the function it documents.

Some of my favorite documentation for a house is a scribble in a closet that says “if it leaks here, check the shower pan of this bathroom”. This is so good: I notice water in a spot, and at that spot, right when I need it, is some information about past attempts to solve the same leak.

For similar reasons, I really like kitchens where cabinets are labelled. Sure, if I spend a lot of time in a kitchen, I know where everything is. However, I often live with other people, and now we don’t have to make this something we discuss more than once (“wait, I thought the spatulas went there?” “No, I thought we said they’d go over here instead?”). Signs just alleviate this problem entirely. It’s also not in some meetings notes, or in a wiki: it’s in the kitchen, the spot where you need this knowledge. It also makes it much easier to have friends come over and be effective in a kitchen they don’t know.

A few more kitchen examples (why so much focus on a kitchen? It’s the space that I share the most with other people. Same applies to workshops, or multi-developer codebases). Having a sign on the dishwasher that says clean/dirty. The documentation for the state is so close to the object itself that it is usually reliable. So is putting a date on leftover food. I usually remember what I cooked, and when I cooked it, for a few days. But that onion? Was that from yesterday, or a week ago? or longer? It also makes fridge cleanout easy “wow, this is multiple months old, oops”.

I could go on (clearly) on more examples, but I want to generalize a little bit. The real value in the label is that is is attached to the object it documents. It is easy to assign the value to “oh, someone took the time to document this”, which although valuable, is only useful if that information is retrievable later. By having the documentation intrinsically attached to the object it is documenting, we have made sure it is going to be useful later on.

Let me rephrase the above paragraph in a slightly more abstract way. The value of labels is in unifying two separate things: the object in question, and information about said object.

In fact, I believe that “making one from many” is the heart of very many computer systems. A file is a collection of blocks on a storage device. Dynamic vectors (linked lists) are a very similar example of the same. Git commits make changes across many files one. In general, this is the principle concept behind atomic transactions.

Fundamentally, “make many things one” is abstraction. A function takes a sequence of steps and groups them together under one process. In object-oriented languages, a class does the same thing with multiple functions and data.

Changelog

Tuesday Jun 10 2025

• Initial draft and thought-dump