Sep 1, 2021, 1:05 PM ETInterview

Writing, Technically with James Somers

James Summers currently spends approximately 75% of his time writing code and 25% acting as a "writer or editor in residence" focused on documentation.
His approach to writing is grounded in his identity as a software engineer first; he argues that effective technical writing requires deep empathy for the specific, unique ecosystem of Jane Street (including OCaml, custom standard libraries, and in-house tools).
Summers views his primary function as a "perpetual outsider" or the "dumbest person who can understand the topic," ensuring documentation is accessible to readers with varying levels of patience and expertise.
He aims to counter the tendency for documentation to become neglected or a "backwater" because it is often less exciting to write than new software features.
The role is critical for creating "searchable trails" of knowledge, addressing the cultural issue where institutional knowledge is stored in phone calls between specific owners rather than in written records.

Jane Street's culture is described as "human-centric," where code ownership is assigned to specific individuals who act as the primary source of truth, often via phone calls rather than written guides.
This culture has historically hindered scale as the company grew from 40 employees to approximately 1,500 over nearly 20 years.
Summers compares the current state of documentation to the state of testing a decade ago: testing was once "thin" and reliant on small teams and type systems, but eventually became a pervasive, tool-supported culture; documentation requires a similar transformation.
A key friction point is that improving documentation is a "multiplayer game" where the writer often incurs immediate costs (time and effort) while the benefits accrue to the organization or future users, unlike testing which offers immediate personal productivity gains.
The organization struggles with the "curse of knowledge," where experts produce overly concise, formal-grammar-style documentation that fails to guide new users.

Summers developed a "literate docs" system where documentation includes executable code blocks that are compiled as part of the build system to prevent documentation rot.
If underlying APIs change and break the documentation examples, the build fails, providing a mechanical incentive to update the text.
He built an internal publishing platform that includes social feedback mechanisms, such as view counts and "likes," to incentivize authors by showing the impact of their work.
An internal search engine is being developed to index wikis, API docs, blogs, mailing lists, and code review comments to improve the discoverability of existing documentation.
Tools are designed to provide feedback loops, reminding developers that their documentation is being read or that it has become stale due to code changes.

Summers rejects the trope that code should be "self-documenting" to the point where comments are unnecessary, calling it a delusion, particularly in the Ruby community where complex DSLs often hide massive implementation complexity behind clean APIs.
He argues that type systems (like OCaml's) are powerful for clarifying input/output constraints and data semantics but cannot express runtime complexity, subtle OS interactions, or design trade-offs.
Writing documentation is framed as a diagnostic tool for the author; the act of explaining a system often reveals conceptual bugs or logical flaws that were not apparent during coding.
The interview notes that commit messages often serve as a catalyst for reflection, where the effort to explain a "terrible decision" forces the writer to rewrite the code to be less terrible.

Summers advocates for a "choose your own adventure" approach, creating distinct documents for different reader archetypes (e.g., tutorials for novices, API transliterations for experts, and concise guides for those familiar with the design space).
He references the "four quadrants" of technical documentation: Guides, Tutorials, References, and Explanations, urging teams to explicitly define which types they produce.
He introduces a potential fifth genre: "Evangelism," which aims to be expansive, persuasive, and exciting about a tool, noting this is culturally difficult in Jane Street's precise and cautious environment.
A proposed writing model involves optimizing for reader attrition: ensuring the title conveys the core idea, the abstract delivers the conceptual framework, and subsequent sections provide increasing detail, similar to the "inverted pyramid" style of journalism.

Summers uses a heavily customized version of TextMate for note-taking, utilizing syntax highlighting to distinguish between his own thoughts and quotes from sources to avoid over-reliance on external voices.
He cites journalist John McPhee as an inspiration, noting McPhee's use of a custom editor (KEDIT) to organize notes and detect repetitive vocabulary.
Summers rejects Donald Knuth's "literate programming" (teTeX) as impractical for most, arguing that Knuth's ability to hold massive codebases in his head makes his style idiosyncratic and non-scalable for modern teams.
His writing process varies between "journalistic" (interviewing experts and exploring the subject first) and "stream of consciousness" (if the structure is pre-cached), but he universally advocates for aggressive editing and compression.
He emphasizes that the majority of technical writing is actually email, urging developers to apply the same rigor to internal communication as they do to public tutorials.

The Rust API documentation is highlighted as a gold standard for its consistency, heavy use of examples, and direct linking to source code.
TensorFlow's "Getting Started" tutorial is praised for its clear, example-driven approach to teaching complex concepts like handwritten digit recognition.
David Goodsell's biological illustrations and the book Defining the Wind (about the Beaufort scale) are cited as examples of "warping reality" to make complex or invisible concepts salient through illustration and narrative.
Summers concludes that "technical writing" is fundamentally human, relying on the writer's judgment to filter out boring details and highlight what matters to the reader.