Interview
Writing, Technically with James Somers
- James Summers intends to allocate approximately 75% of his time to coding, with the remainder dedicated to documentation, while Ron Minsky anticipates a continuing organizational shift toward prioritizing documentation to compensate for the loss of institutional knowledge as the company grows by orders of magnitude.
- Summers predicts that writing documentation immediately after software implementation is suboptimal due to immersion in implementation details, and notes that a culture associating software with specific owners risks reducing documentation to a list of names rather than a searchable trail.
- Plans to prevent documentation decay include developing tools for "literate docs" where code blocks compile, publishing to a website with analytics and social feedback features, and utilizing a new internal search engine to index wikis, code reviews, and mailing lists.
- Risks and challenges identified include documentation becoming neglected or "rotting" when not maintained, the "delusion" that self-documenting code is sufficient given type system limitations, and the potential immediate reduction in individual developer productivity when adopting documentation-driven development.
- Summers expects documentation-driven development to provide delayed personal payoff compared to the immediate utility of testing, while Minsky notes that the benefit of well-documented codebases for understanding changes is significant but smaller in scale than the impact of testing.
- The outlook suggests that the current transition to a documentation-focused culture is incomplete compared to past shifts in testing practices, and that the move from authored to maintained software creates significant architectural challenges as multiple maintainers enter the picture.
- Expectations for documentation style include adopting the "dumbest person" persona to suit impatient readers, optimizing for early information delivery via clear titles and abstracts to prevent readers from dropping off, and balancing "warping of reality" for salience against the constraints of a careful corporate culture.
- Material predictions regarding the ecosystem include a lack of established technical documentation genres, the difficulty of integrating "evangelism" into precise cultures, and the likelihood that developers will eventually recognize writing as a primary mechanism for storing knowledge, often indicating underlying conceptual bugs.
- Specific constraints noted involve the severe limitations of type systems in capturing performance characteristics, the unsuitability of Knuth's literate programming advice for most brains and large-scale programs, and the difficulty of modifying editors for specific writing needs.
- The timeframe for realizing these shifts is indefinite, with Minsky noting the organization has "a couple of orders of magnitude" to grow before reaching the scale of massive tech firms, while Summers expresses uncertainty regarding whether developers will ever achieve a productivity breakthrough specifically from better documentation.