Legibility Confusion

I am becoming obsessed with legibility. In particular, obsessed with the ever more pervasive, frankly arrogant assumption that all things worth doing in the world are either legible by default, or trivially easy to make legible by software engineers … software engineers.

What is Legibility?

Legibility as a concept is best known by its appearance in the 1998 book, Seeing Like a State, however, the audience to this blog may find this article, Seeing Like a Software Company, to be a more familiar introduction.

To give a brief definition, legibility can be thought of as the propensity for a given endevour to be fully understood and catalogued, almost always within textual formats. Some examples might be:

- Feed a family a meal that nourishes the heart and the mind. This is a very illegible task. There is endless room for debate and interpretation as to what the intent is here. It would be difficult to conclusively prove that any action taken to fulfill this task meets the requirements, or to catalogue specifically all the effects fulfilling the task will have. Nonetheless, you might get some good meals and happy families out of it.

- Produce 3000 calories of edible food and deliver it to the state registered address of family X. More legible, although still can be interpreted in many different ways. We’ve lost some of the spirit of the task in an attempt to gain legibility, but maybe that’s worth it for the benefits we might find in now being better able to manage and catalogue this task at scale.¹

You can imagine if we keep going down this path we’ll end up with something like legal contracts or formal technical specifications. The experienced engineer will know well how that sort of contractualism can be a noble impulse, but has many severe trade-offs and doesn’t tend to work out so well if you lean heavily into it all the time.

Just for fun, and to make sure we’re all on the same page, here’s my off-hand attempt at a perfectly legible task :

- Via exclusive use of the Bunsen-burner provided, maintain a temperature of 100 degrees Celsius, as registered according to the readout on the thermometer already placed in the vessel, of the already prepared 100ml of water at the specified location, for a period not shorter than one minute, according to the clock also already in place at the specified location.

This still has holes, I suspect you need to drop into a more formal specification language to really nail this sort of thing down, but you get the gist. It is convenient that we have a scientific tradition to lean on here that has done decades of work to standardize and contextualize measurement units. Imagine trying to legibly document this task without agreed upon temperature, volume, or time units, as well as making commonplace the means to measure them.

As legibility grows, declarations of tasks must necessarily begin to include instructions on how they are to be measured.² One could presume that legibility is a two phase property, requiring both a task definition as well as evaluation criteria.

Whilst it would be difficult to misinterpret this task, it’s also now so devoid of meaning as to appear absurd. This is the tricky trade-off, human-centric value is difficult, perhaps impossible, to measure, and so cannot be easily made legible.

Non-Oppositional Dualism

Those of you who have read some of my previous writing may know that I hold an almost religious reverence for the practice of engineering. Its divinity allows us to consciously decide the shape of the future via consent from the transcendentally human bits of ourselves. It is tempting to frame this reverence for personal divinity in opposition to the mundane materialism of the deterministic animal self, but to do so would be foolish. We are not in opposition to ourselves, and if we are to perceive ourselves as a dualism, we are a non-oppositional dualism.

I don’t think that interpretation is particularly unusual, these sorts of non-oppositional dualism’s pop up everywhere, from modern technical literature to academic philosophy, here are some examples :

Whilst not universal, one could argue some of these dualism’s are precisely the same concept. To avoid confusion, I’ll just stick to talking in terms of legibility & illegibility.⁴

I’m not here to argue that we’re over-indexing on either legibility or illegibility. No, these are contextual, ever shifting qualities that reflect and require each other, and I couldn’t make a universal judgment. Grappling with this balance, and trying to deduce and intuit what is and isn’t worth trying to make legible is a noble act that we should do more of. Some might think we should put in the effort to make everything as legible as possible. It’s an extreme position, but not irrational.

No, what I’m here to argue is that we are suffering from an increasing delusion that legibility can merely be assumed to exist without any of the trade-offs it implies, or almost any of the effort required to achieve it.

I wonder if you can recall the feeling of being asked if it is finished yet, and struggling to understand what the person asking means by it? You know what you mean by it, but you also know that it is so nebulous, undefined, and tied up with personal, incommunicable context that it couldn’t possibly be the same thing that they mean by it. You wonder if they’re interested in your personal intuitions, but they get frustrated when you try to express yourself in probabilities and suppositions. This is puzzling, as probabilities and suppositions were your best effort to compress the multi-dimensionality of illegibility into something approximating the legibility you were being asked for.

You’ve probably been asked to provide time commitments to tasks without much definition to them. Perhaps you’ve even tried to extract a concession that these estimates are meaningless and probably do more harm than good, only to be met with a sort of glazed disinterest.

Certainly you’ll have come across a keen interest in whether a Jira ticket (generally the ultimate home of legibility confusion) can be moved to the done column. You take up the conversation about consequences of the present implementation and the implications it already is having, etc. Yet again, glazed disinterest. Focus on getting tickets into the column please.

This effect appears to be rising. Interest lies less in the delivery of the human value that work represents, or even in the technical delivery of any specific piece of work. We care now more and more about the symbolic completion of tasks and the performance of delivery. It’s said sometimes that engineers could simply start moving tickets into the done column without actually doing any of the work behind them, and organizations simply would not notice. This is uncomfortably true. I fear the new generation of engineers are so brainwashed by the capitalist-realist miasma, they will find themselves unable to distinguish between final value and the symbols that supposedly represent it. Moving Jira tickets, gaming benchmarks, generating market hype, that is the work, right?

I trust that I do not need to explain the consequences at length. Despite our insistence on systems that exist primarily to enforce legibility, we are still very confused about the whole affair. As we pat ourselves on the back, end-users are the first people to notice poor quality, broken promises, and sometimes dangerous behaviours. Our systems are so well adapted to providing the illusion of legibility, we will be the last to hear about any problems in what we’re doing, if we ever realize at all. Revenue may drop, but that will be easily explained away by poor market conditions or other unavoidable external circumstance. The human mind is incredibly well adapted to post-facto narrativization of scattered data. The will always be a story.

It is this confusion, this delusion, that is our rising problem. Consider how one could even identify this issue in an organization where the reasoning model of the organization is constrained to these “legible” systems? The necessary information is inexpressible!

I can and do respect people who are in my view overly focused on the benefits of legible project management, just as I can and do respect people who perform the opposite. However, this repugnant null-space where one believes they are performing legibility but are actually observing nought but illusions seems to have become our primary method of making economic decisions. Through this lens, it is of no real surprise why global decision-making has become to feel so post-real.

I think there are traceable cultural and economic reasons we find ourselves in this position. Hyper-specialization and Taylorization has bred a generation for which the majority have never been unalienated from the effects of their work. In that landscape, what else can one do but assume there is some sort of spiritual force that takes your efforts and somehow transmutes it into real value.

It cannot be the case that all these TPS reports and sprint ceremonies and test framework refactors are pointless, existing merely as busywork to prop up the illusion of near 100% labour utilization? Surely not. The same religious belief in this deity-like transmutive force powers behaviours like slacktivism, the belief that one can meaningfully make a worldly difference from the comfort of a bedroom keyboard and a comments section. Something somewhere will magically transmute your very important tweets into social progress I am certain. Just keep raising awareness, just keep contributing to the culture, there’s a good lad.

The Convenience of a Legible World

It’s hard not to notice how it would be oh so convenient to a particular class of people if the entire world was legible by default. Both the Metaverse (reified spaces anyone?) and the AI hype bubble can be thought to rotate around this desire. Amazon, Google, Microsoft … these tech giants all do pretty much the same thing at this point. They’re at the saturation point for what they can meaningfully do with software, there’s no reality left for them to expand into. However, if the entire world was a database entry, then software companies can continue to grow into every vertical in every domain for the rest of all time.

I’d encourage you to read Nilay Patel’s piece on Software Brain for more on this.

Reality is, fortunately, not a database. Silicon valley has therefore decided that rather than compromise with reality, they will occupy it. Using their accumulated power and influence, they will change the base substrate quickly enough that the human superstructure will be forced to contort around the new reality, locking in the essentialness of the software giants for all time.

Presently, they are attempting to change all worldy interaction such that it goes through AI systems. However if that fails, rest assured there will be something else, some other reality-engulfing modality that insists that all existence is and always has been reducible to API calls. If that necessitates refactoring away the parts of the world that are not reducible to API calls, love, connection, faith, hope & happiness, etc; well all’s the better.

This is the only thing they can do, as to do anything else would be to stop growing.

These companies may believe that what they are doing is doing the work to make the world legible. Given the confusion in the space, I think this is a reasonable assumption, and the hubris displayed in thinking software engineers can “solve” this fundamentally human dualism with markdown files does not surprise me in the least. Their actions convey a different story however. In this story, the world just is legible, always has been, always will be, and it’s frankly childish to assert that is is not. All things have materialist foundations, with fully deterministic properties both in substrate and macroscopic emergence, and can be fully cataloged and understood without any reduction in meaning or any sort of trade-off. This is trivial to do, and by golly they’ll even sell you the tools to do it, isn’t that convenient!

Large Legible Language Models

I’ve not much to say here at the end about LLM’s. They are bastards in that they can only draw from the legible universe, they are made of language, an inherently legible construct. Any analysis done via LLM’s will only manifest legible modes of thought by definition.

Remember how when LLM mania began, we all started saying how formal specification and extremely clear conceptual documentation was all of a sudden very important? This was a reaction by the people who intuitively got this, that these tools required that we attempt to make what was previously illegible legible, as they could not function in the illegible domain. It remains a pretty astute observation, given what LLM’s are, despite the assumptive and unsubstantiated favouritism towards the legible.

LLM’s, being the accelerant that they are, have poured fuel onto the fire of confusion that has been raging for a while. It’s the same fire that fueled the over-application of Object-Orientation, the misinterpretation of Agile, the unrealized promises of Microservices, the breathless swindles of Crypto, and the fetid disappointment of the Metaverse. I fear it is too late now to guide people out of the inferno. What’s worse is that these fires don’t tend to go out, they linger.

1. It’s curious to me that whilst we have lost some of the flexibility of the original intent in that we now have specific calorie requirements, it’s not a one-way tradeoff. “3000 calories of edible food” could be interpreted by bad actors as barely edible, in context one could almost argue the clinical phrasing of the task implies that to be the case. Looking at it this way, the first, less legible task can be thought to be more highly constrained on some axis’s rather than less, as it would be hard to argue to a reasonable actor, (read: judge) that barely edible slop fulfills the stated requirements. You see here how illegibility can have societal advantages in its constraining power as well as its unconstraining power.

2. Despite how much gesturing at agile practice is done here, this strikes me as the core motive behind behavior-driven-development, and formalized behavior specification languages like cucumber. The Cucumber docs purports that BDD “closes the gap between business people and technical people”, which would be read to mean that it tries to stop software people working in illegible ways so business people, who cannot easily engage with that illegibility, can participate. Never seems to swing the other way though...

3. I was tempted to list Fred Brooks’s accidental and essential complexity from “No Silver Bullet” here as well. It would be a tad provocative, as most folks would argue that accidental complexity is a negative quality, and is in opposition to essential complexity. Some might make the same assumption about illegibility though.

4. I’m no researcher, but Korzybski’s Map & Territory is arguably the originator of these dualism’s in the modern technical tradition. I suspect there are more parallels to be drawn in the academic machine learning space, but I don’t want to overly embarrass myself by mentioning them.