James Somers on Technical Writing, Software and Revision

Ron Minsky introduces James Somers, a professional writer and software engineer who works at Jane Street. Somers says he spends roughly three quarters of his time coding and the rest acting as a writer and editor in residence, helping colleagues write and improve documentation.

Somers believes being a working programmer first helps him understand the organization he writes for. Jane Street has its own OCaml libraries, development tools, testing and build systems, deployment practices and monitoring. Empathy for a developer in that unusual ecosystem comes from experiencing it directly.

Minsky agrees that good writing depends on understanding its subject, but asks why an organization needs a person especially focused on writing. Somers says documentation is difficult and easy to neglect, particularly when new software feels more exciting than explaining existing work.

The moment after building a library can be a poor time to document it: its author is immersed in implementation details rather than an outsider’s questions. Somers describes his role as being a perpetual outsider, aiming for the level of understanding a busy or impatient reader may have.

Jane Street is conscientious about documentation and invests in tools to keep it current, Somers says, but it still faces familiar problems. Its culture strongly associates software with the people who build and maintain it, so an answer may be a phone call to the right person rather than a search result.

The code-review system records file ownership, making it possible to find the people most familiar with a part of the code. A list of project owners can itself be useful documentation. But a phone conversation leaves no searchable trail for someone who joins later or was not present.

Writing stores knowledge over time and distributes it at scale. Minsky recalls Jane Street growing from roughly 40 people to 1,500 during his tenure; specialized systems and low turnover had produced deep individual expertise, but increasing scale made recording that knowledge more important.

Minsky compares documentation to the firm’s evolution in testing. Early systems relied more heavily on a small group’s knowledge and the protections of OCaml’s type system. As the codebase grew, people built testing tools and made testability a pervasive concern; he wants a similar cultural shift for documentation.

Somers sees a difference in incentives. A test harness can make the author’s own development work easier almost immediately, whereas documentation often initially imposes work and primarily helps other people. An organization may need to recognize the collective benefit even when the individual author does not experience an immediate productivity gain.

Minsky replies that testing also has a shared benefit: a well-tested codebase gives colleagues confidence to change unfamiliar parts. Good documentation similarly helps people learn and modify an unfamiliar system, though authors may need other forms of feedback about its value.

Somers works on literate documentation: Markdown files contain code blocks that compile. If a library API changes and an example breaks, the build flags the documentation just as it would code. That does not solve every documentation problem, but it helps counter stale examples.

He also works on publishing documentation from the build system to an internal website. Features such as readership counts, comments or likes can give authors a sense of the effect their work has. An internal search engine can bring together the wiki, literate and API documentation, blogs, mailing lists and code-review comments.

Even an excellent document or tool is of little use if people cannot find it. Minsky summarizes three roles for the tooling: discoverability, social feedback about a document’s use, and a connection between code changes and documentation that needs attention.

Somers adds that a broken documentation build is more than a mechanical error: it prompts the developer to revisit the explanation and decide whether it still makes sense. Knowing that a page is read can motivate improvement; knowing that no one uses it can also inform where to spend effort.

Minsky describes starting code review with explanations, comments and names before reading the implementation. He often asks an author to clarify a feature or writes documentation during review. The process can reveal conceptual mistakes and real bugs, not merely improve the wording.

Somers recognizes the same pattern in a long commit message that tries to explain away a poor decision. Imagining a reviewer confronting the explanation can make him realize the implementation itself was only a first draft. Both writing and code may need to be redone.

Asked whether programming and prose feel similar, Somers says they differ at the small scale. Programming has fewer degrees of freedom because language and library constraints narrow the choices; prose permits many more ways for a sentence, paragraph or whole piece to go wrong.

At the larger scale, the crafts share a willingness to revise. Somers compares it to a distance runner’s tolerance for miles: strong programmers, like writers, repeatedly return to work they thought was finished. Minsky adds that code organization, names and comments can tell the structural story of a system.

Both kinds of work require modeling the reader and organizing one’s own thoughts. A long, strained explanation can also indicate that the underlying design is more complicated than it needs to be.

Minsky asks about the claim that code should be so clear it needs no documentation. Somers has seen a strong version of that idea in Ruby, where expressive domain-specific languages can look almost like English. But an elegant interface can conceal complicated implementation machinery that deserves explanation.

Some useful information does not sit naturally in code: for example, the runtime complexity of a function or guidance on choosing among data structures. Somers recalls an asynchronous file-writing API with an exclusive flag; a multi-paragraph comment explained the subtle operating-system and locking issues that the flag alone could not convey.

Minsky argues that even sophisticated types and clean abstractions have limits. A macro can expose translated implementation details in an error, and practical type systems cannot express every relevant property. A simple-looking interface rarely eliminates the need to explain its behavior and tradeoffs.

Somers nevertheless sees self-documenting code as a useful nudge. Instead of passing unvalidated strings for a social-security number and vaccination status, a program can use meaningful types with validation and methods. Minsky notes that these types make the meaning of values visible throughout the program, and an editor can show a local variable’s type.

They consider whether languages determine documentation and testing cultures. Somers recalls a Ruby on Rails consultancy committed to test-driven development, but says application context matters: trading systems have different failure costs from a small web company testing whether users like a feature.

Minsky adds that culture and architecture can matter as much as language. When Jane Street rewrote early systems in OCaml, the team, architecture and practices also changed. Somers has seen both poor and good designs while using the same language and even the same programmers.

Minsky observes that some OCaml documentation is concise and precise but assumes readers already have a mental model. He asks Somers, who often writes example-driven guides, about the tradeoff between compact descriptions and examples.

Somers recalls his first documentation assignment: improving the README for a tool that queries S-expressions. The existing document was essentially a formal grammar. It was hard for a newcomer to see what the tool was good for or what practical tasks to perform, so he wrote an example-driven guide.

Minsky remembers that the original author knew the document could be improved. A formal description made sense to someone with a strong programming-language background, but could reflect a curse of knowledge. Still, concise material can be exceptionally efficient for an experienced reader who already understands the design space.

Somers suggests serving those audiences with separate documents that identify their purpose. For an OCaml web framework, a beginner may need a tutorial explaining the browser context; a React user may prefer a mapping between familiar APIs and the new tool. One document cannot meet every reader at once.

They discuss four documentation forms: tutorials, how-to guides, reference and explanation. Minsky recalls advice to put useful information early in an academic paper, since readers drop off at different points. He wonders whether tools could also let readers move between a compact type view and examples.

Somers says conventions create genres that help both writers and readers navigate. Newspaper stories often start with the most important facts, while experienced academic readers know where to scan for results. Recognizable documentation genres could similarly tell readers what to expect and writers how to structure a document.

Minsky proposes another category: writing that persuades people to try an idea or tool. He thinks careful, precise engineering cultures can make this kind of advocacy difficult. Somers notes that without a compelling case for one tool, an organization may end up with several similar alternatives.

They turn to Donald Knuth’s literate programming. Somers found some descriptions and examples difficult to follow. Minsky outlines Knuth’s work, including TeX, and asks how the approach differs from ordinary code and documentation.

Somers describes interleaving code and prose so the reader follows a linear explanatory narrative rather than jumping among files. Minsky adds that the published narrative can order sections differently from their arrangement in the source, presenting an entire program in an order chosen for explanation.

Somers thinks the approach may be powerful in the hands of a master such as Knuth, but difficult for most programmers. Minsky contrasts Knuth’s comfort working across deep layers of a system with his own need for abstraction to understand complex software. Practices suited to a single exceptional author may not scale easily to larger programs.

Somers says software created by one person can have a different architecture from software maintained by a team; the transition between them is particularly challenging. They acknowledge the continuing impact of Knuth’s work while questioning how broadly his individual methods apply.

Somers uses TextMate for notes and customizes syntax highlighting. He distinguishes his own thoughts from quotations and can visually spot a draft that quotes sources too heavily. For collaborative editing or later drafts, he often moves to Google Docs.

He describes nonfiction writer John McPhee’s customized KEDIT environment, which helps organize notes into nested groups and identify repeated unusual words. Somers would like more writers to be able to adapt their tools without needing deep technical knowledge.

Minsky asks whether Somers plans the structure first or writes from beginning to end. Somers says the process depends on how much he must discover. When documenting an unfamiliar library, he acts like a reporter: talking to people, reading, trying the tool and organizing notes before building the explanation.

Even when a structure comes easily, another draft can improve it. Somers compares editing to compressing text: a message often contains far more words than the meaning requires. Minsky adds that shortening can also clarify the point and effectively add useful information for the reader.

Somers gives an example of an email containing a 14-line exception trace. Rather than paste everything and tell the reader which lines matter, he could remove irrelevant lines. His advice is to reread and revise rather than treat a first draft as finished; Minsky sometimes discovers on revision that an email need not be sent at all.

Much technical writing is ordinary email rather than a formal guide or design document. Since email consumes colleagues’ time constantly, Somers argues that a little extra care there can make a substantial difference.

Asked for examples he admires, Somers mentions Rust API documentation with consistent examples and links to source, and TensorFlow’s introductory handwritten-digit tutorial. He also looks outside software, including molecular biologist and artist David Goodsell’s illustrated explanations of proteins.

Somers cites Defining the Wind and the Beaufort scale, whose descriptions translate wind speeds into observable details such as moving leaves and flags. He finds poetry in precise language that helps a reader recognize a physical phenomenon.

A drawing of a coastline can sometimes communicate its salient features better than a photograph, because the illustrator selects and emphasizes what matters. Somers sees effective technical writing doing a similar transformation: shortening, illustrating and making the important parts easier to perceive.

He advises writers to trust their own response to what is interesting or boring when exploring code or a library. Recording those reactions can produce an explanation that is less formal or comprehensive but more useful to readers who share the same questions. Minsky concludes that technical writing is deeply human as well as technical.

Somers dislikes the dull connotations of the title “technical writer”: the work is not fundamentally separate from other writing, and people practice it constantly. Minsky thanks him for a conversation about a subject they both work with often but rarely get to discuss at this level.