Software Engineer as Journalist
When I read Clean Code, there was one passage that stuck with me more than any other. Robert Martin was writing about the structure of code in a way I hadn’t heard anyone do before (he’s referring here to what journalists call the “inverted pyramid”):
We would like the source file to be like a newspaper article. The name should be simple but explanatory. The name, by itself, should be sufficient to tell us whether we are in the right module or not. The topmost parts of the source file should provide the high-level concepts and algorithms. Detail should increase as we move downward, until at the end we find the lowest level functions and details in the source file.
Recently, in light of public criticism of Mr Martin by a number of folks in the software community, I’ve been thinking about what value I got from his work.
More than the SOLID design principles, this passage planted a seed that started to change my thinking about what it means to design software: We are writers as much as we are engineers.
Over time this seed grew for me, fed by the ideas of folks like Jessica Kerr, leading me to think about code not as not just a machine or structure, but the connective tissue of a social system, comparable to the way that authoritative newspapers can provide a set of facts and narratives that become the strongest fibers in the social fabric.
Reflecting on this paragraph, I realized we can take it much further, using the analogy of software developer as journalist in more fundamental ways than the structure of modules.
How can software engineers act as journalists within organizations?
Report on significant events & states in the system
One of the primary jobs of a journalist is to help make important events in a social system visible. Who won an election? Did a Senator change their stance on an important issue? Is an important resource close to being depleted? Is a new law coming into effect?
Similarly, software engineers work to reveal system events & state. Often the event is localized to a single user: return a comprehensible error message. In other cases we may need to build a resilient status page that can give accurate information about a system, especially when it is in a general state of failure.
Another example is more like traditional journalism: the “postmortem” or retrospective of a significant disruption to the system. Here we want to write the story of the event, as it was experienced by those closest to it. This process may involve conducting interviews, uncovering documents & artifacts that tell the story. When done effectively, this can help everyone, at all levels of the organization, avoid similar disruptions in the future. Just communicating these stories in an unbiased way changes the system, as the human components of the system develop a deeper understanding of the system.
Help define a shared language
Usually part of the work of engineering is to listen to domain experts, understand their mental models, and translate them into data structures while retaining their terminology. Sometimes we need to uncover terms that are used to mean different things by different people, or in different situations, within the same domain, and find a way to disambiguate.
This is a big part of a journalist’s work as well. Importing industrial, political, and military jargon — eg “fracking”— into wider usage allows the public to grapple with systemic changes and major events more easily. Because engineers are putting names to the database tables, the object classes, the API verbs, the UI components, the input labels, they have an influence over the language used within the organization. To the extent that this process is more journalistic in nature — written to be precise, and understood by a wide audience, regardless of technical knowledge — the communication overhead of the entire organization can be lowered.
One thing I want to emphasize here. Sometimes in software companies we refer to people as “technical” — meaning having knowledge of computer systems and how to manipulate them. But the truth is that usually the domain (business) experts are just as “technical” as engineers, in a different field.
Like journalists, engineers need to learn how to gain access to these experts, ask the questions that will most quickly reveal their knowledge, and find ways to accurately encode and effectively spread that knowledge throughout the system.
Reveal the structure of the system
As with naming, journalists help citizens understand the relationships between different parts of society through narrative. It might be a story that captures the relationship between business executives and regulators, the housing market and the banking industry, or the food bank and farms.
Each of these stories help us build a mental model of our society, and affect the way laws are written, votes are cast, money is spent, cases are prosecuted.
Engineers and data analysts often play a similar role in helping to measure the ways one part of of a software system affects other parts. In many cases the stories seem more mundane than the examples above (but, in many cases, journalists are also writing more mundane process stories): service A became a bottleneck leading the queue in service B to grow out of control.
In other cases, spending time measuring the way features we develop are used by the people our organizations serve leads to fundamental strategic insights about the systems we’re building.
We aren’t journalists
It should go without saying, but to be clear: we don’t do this work all of the time. There are usually teams in a software organization adjacent to engineers who work on these problems as well — project managers, designers, business intelligence, and many others. Sometimes even real journalists.
But these skills are important to have in any engineering team, because it’s very difficult to do quality engineering work without being able to accurately describe the system you’re building (or, at least, parts of it).
