On Naur’s Documentation Pessimism
In 1985, Peter Naur argued that programming is theory-building, and that theory cannot be fully captured in documentation. But his pessimism is narrower than supposed. It applies to technical documentation of artifacts, not documentation as a human endeavor. AI doesn’t “solve” the problem—but it creates conditions where theory transmission becomes more likely.
In 1985, computer scientist Peter Naur published “Programming as Theory Building”—a short, influential essay arguing that programming is fundamentally about building mental models, not producing code. The programmer’s theory of how real-world problems map to software is the essential product; code and documentation are secondary artifacts. Crucially, Naur claimed this theory cannot be fully captured in documentation, because it involves tacit knowledge that defies formalization. (See our summary or the original paper.)
But Naur’s pessimism targets technical documentation—specs, code, design docs—not all written communication. The Renaissance proves documents can transmit theory when written to do so.
AI collaboration doesn’t solve the documentation problem by reducing labor (that misreads Naur’s epistemological argument). But it creates novel conditions: forced articulation, preserved dialogue, lower-friction iteration. These make theory transmission more likely, even if never complete.
Chapters
- Preface — Who wrote this, and why the strawman caveat matters
- Naur’s Actual Argument — Epistemological, not economic
- The Strawman to Avoid — What AI doesn’t solve
- The Scope of Pessimism — Artifact-focused docs only
- Evidence from Cultural Transmission — The Renaissance argument
- Why Technical Documentation Fails — Cockburn’s analysis
- Forced Articulation — AI as interlocutor
- Dialogue Preservation — Capturing the problem-solving process
- What Remains Unsolved — Tacit knowledge persists
- Toward Theory-Resilient Documentation — Practical recommendations
- Conclusion — Synthesis
References
- Alexander, C. (1977). A Pattern Language. Oxford University Press.
- Alexander, C. (1979). The Timeless Way of Building. Oxford University Press.
- Cockburn, A. (2006). Agile Software Development (2nd ed.). Addison-Wesley.
- Kernighan, B. W., & Plauger, P. J. (1976). Software Tools. Addison-Wesley.
- Kuhn, T. S. (1970). The Structure of Scientific Revolutions (2nd ed.). University of Chicago Press.
- Naur, P. (1985). Programming as Theory Building. Microprocessing and Microprogramming, 15.
- Polanyi, M. (1973). Personal Knowledge. Routledge & Kegan Paul.
- Ryle, G. (1949). The Concept of Mind. Hutchinson.
This document is living. It evolves with our practice.