Issue #15: Writing

Why My Team Writes

Writing is one of the most disruptive technologies ever invented after agriculture. Before writing, people could pass information in the current moment, to those who were close enough to hear noises made by other people. Writing allows people to communicate across space, passing written information to readers without the physical presence of the author. And it allows them to communicate across time, leaving evidence of thoughts long after the thinker had died.

As software engineers, our job is basically to wrangle information and make it useful. We might as well be called “informaticians”—and in many languages, we would be. The information we work with takes multiple forms.

Information About Problems

Sometimes we call them requirements, sometimes stories, sometimes domain knowledge. We often need to record information about how the world works, or how people work with the world, or how people work with each other in the world. This information helps us to identify problems people have, that we might be able to solve using computers.

It also helps us to identify people who have those problems, or “potential customers”. Someone who can see that we’re thinking about their problem can consider engaging with us to determine whether our solution is valuable.

Information About Solutions

My colleagues and I need to agree on what the thing we’re building does, and how it does it. We draw box-and-arrow diagrams showing our thinking, we write READMEs telling each other how to set things up, and comments and wiki pages describing particularly complex parts of the solution or hard-won nuggets of domain knowledge that have made their way into the code.

We write messages in our automated tests explaining what it means to the app if a particular assertion fails. We do the same thing in assertion expressions in the code, too. We name things to help people understand what they do.

And, of course, we tell those people who have the problem what our solution is, how it works, and how they can use it. This is the part that turns them from potential customers into actual customers. Or into not customers, with reasons for not being customers that are useful information in themselves.

Information About Technology

We make cases for using particular tools. We explain tricky things about the tools we are using. We write training materials for people who want to learn about the tools we’re using. We write blog posts describing our experiences with those technologies. We make records of decisions that we made, and alternatives we rejected.

Information About People

We document our expectations of interactions with each other. We reflect on how our work has proceeded, and we write about what we’d like to change. We write about what we’re planning to work on next, and whether we’re stuck on any of it. We write descriptions of the people we want to work with, questions to ask to discover their suitability, and evaluations of their answers.

Cover photo by Florencia Viadana on Unsplash.

Graham is the chief labrarian of The Labrary, where the library and the laboratory intersect. He got hooked on making quality software in front of a NeXT TurboStation Color, and still has a lot to learn.