Documentation cannot--and so need
not--say everything. Its purpose is
to help the next programmer build an
accurate theory about the system.
Everyone involved in software development should read and understand it!
It's not obvious how thinking about programming as theory building will help with any part of this. The real problem seems to be poor communication between projects and developer groups, with the implication that any self-guided learning approach can't possibly work because it's impossible to communicate the "why" of code without having someone who does understand it explain it to you.
It's an interesting point, and in some ways explains a lot. But I see no reason to think that "theory building" - which really means teaching domain expertise external to the code - is a practical solution in most projects.
Everyone builds models about the world around them (Naur used "Theory" instead of "Model" but they're the same here). Not all models are as accurate as others, though they may be sufficient for many situations. The developers of a system (most likely) have the best model of how the system operates and is constructed. Operators have a separate model. Maintainers have a third model. By separating the initial developers, operators, and maintainers, and reducing communication to, primarily, the exchange of programming notation and documentation, three different models (at least) will be produced. Incorrect models lead to incorrect usage and incorrect maintenance activities.
If your programs are short-lived or very simple, this paper is of little utility to you. But if your programs are expected to live for a decade or more, or are very complex, the ideas here are more useful, probably critical to the longterm success of your enterprise.
I work (or have worked) on systems that were developed over 30 years ago. A lot of knowledge has been lost, and a lot of wheels get reinvented. Or components of the system go underutilized, or misused because of misunderstandings of how the system functions and was designed. The more successful projects have had people working on or with them for 10+ years. Without them, program modifications have usually been small (large changes were seen as untenable), complete rewrites (because no one understood it), or failures (long delays, maybe a working product at the end, often with one or more rewrites along the way).
In my opinion, this is spot on and an important insight into programming.
The validity of this view of programming is particularly evident when using a logic programming language like Prolog or Mercury: In this case, the programmers' task is to describe what holds, and the clauses that constitute the program and their semantic consequences are literally the theory of interest.