Corporate legibility is the art of making tasks, and their outcomes, easier to understand for those not directly involved. I’ll help you understand why this is an important thing to be aware of and how to use it to help your career.

Introduction

First, some definitions. I’m using “corporate” and “corporation” to mean any business organisation. It doesn’t matter how large, but generally deliberate legibility efforts happen when the organisation size eclipses Dunbar’s number – around 150 people.

I’m using “legibility” as it is used in Seeing Like a State by James C. Scott, where it used as a short hand to describe efforts to allow those involved in statecraft (administrators, rulers, etc) to make sense of a complex and chaotic world.

Corporations of a certain size behave much like (early-modern) states - generally the executive leadership team can be seen as the head of state, perhaps the board as senior members of the clergy, and then a network of fiefdoms producing some form of output to grow the business.

As a result, they employ similar statecraft techniques - employees are reduced to “resources” or “heads”, the world is perceived through abstractions such as reports and dashboards, analogous to maps and chessboards. Some business leaders even appear to take inspiration from literature intended for rulers, such as Il Principe and The Art of War.

It is important to remember these efforts are not intended to benefit you, the engineer, directly. They are there to make the work easier to administer, and to make the work visible up the chain so the head of the corporation knows just what the people they employ are doing for their enterprise.

These legibility efforts, although useful for the administrator, often have negative effects on the folks doing the work. We will explore “the legibility trap” and then explore ways to minimise the negative impacts these efforts can have.

The Legibility Trap

In Seeing Like a State, Scott gives us this powerful statement:

Every act of measurement was an act marked by the play of power relations. ¹

Power is at the heart of all acts of measurement in a corporate setting, even if the intentions are good. This is the legibility trap - as soon something is quantified, power is given to the measurer. Measures often become targets (and fall afoul of Goodhart’s Law), but even non-targets can be used in both overt and covert methods of coercion and control within an organisation.

A good example of this is the use of “developer productivity metrics” to help managers make sense of engineering output. A metric I have issues with in particular is “code coverage”. Ostensibly, a manager being able to see a code coverage metric allows them to get a sense of how under-tested the software their engineers produce without having to understand the code itself. Of course, this becomes useless quickly - 100% code coverage means nothing, as the “tests” may be in name only, created only to satisfy the measure and provide no real value.

Along the same lines, there is this brief excerpt from Kain and Baigent’s The Cadastral Map:

The cadastral map is an instrument of control which both reflects and consolidates the power of those who commission it. ²

Scott provides another insight into why the trap can be deleterious to an engineering team:

What was simplfying to an official was mystifying to most cultivators. ³

The context of this statement is around French-colonial era Vietnam, where the asymmetry arising from an illiterate rural population and a highly-literate administration class allowed the latter to consolidate enormous power. In our software engineering context, we have to understand that the administrators are playing a different game where the rules are poorly understood by the engineers.

This asymmetry not only results in power imbalances, but also frustrations. I’ve been on many teams where the refrain of “why do we have to <update in x/request approval in y/provide change receipt in z>” is often heard. For some reason, corporate legibility tools often have poor UX for those who interact with them who are not administrators.

The trap works both ways, however. The administrator class within an organisation can quickly fall into a pattern of believing the map is the territory and can only perceive the work through the lens of the legibility tools. Much has been said of “data-driven” iniatitives, that are often blind to the innate complexities and vagaries of where engineers meet the problem space, and the perverse incentives that can result (see: the code coverage metric above).

Working the Trap

The trap, sadly, does not appear it can be escaped. Illegibility provides increased autonomy, but at a heavy price - being singled out as “difficult” or “not team players”, or worse, falling afoul of regulatory requirements where the work process must be made legible (see: SOX, SOC, ISO and many other TLAs).

Although the power primarily lies in the administrator class, the engineers are not powerless. By participating in the legibility efforts, they have the opportunities to make the measures work for them. For example, ensuring that impactful work is appropriately visible to the group that can decide promotions is important. Similarly, by making legible all the effort to develop new systems, maintain existing ones and so on, it is easier to make the case for additional headcount.

In terms of engineering, efforts such as SLOs have given rise to increased systems observability, which maps well to legibility projects. These benefit both the engineer and the administrator alike, without particular power asymmetry – though of course, the administrator can easily turn such an objective into a crude tool to shape the organisation as they see fit.

Seeking mutual benefit from these legibility efforts, from both the administrator and the engineer, is the primary way to make the trap work for all involved and to make sure everyone is along for the ride.

Conclusion

Corporate legibility efforts are typically well intentioned, to make sense of the complex and complicated world of software development. As with all attempts at such abstractions, they result in a transfer of power that can chafe against autonomous groups and in extremes, be harmful to the effectiveness of these groups. By ensuring the efforts work on both sides, we can reduce frustration and reduce the asymmetries that result in potentially unfair power balances.