IX. Toward Theory-Resilient Documentation
If we take Naur seriously while acknowledging the genuine (if limited) changes AI enables, what practices follow?
Document Theory, Not Just Artifacts
Alongside (or instead of) specifications and API references, maintain documents that address:
- Why the system is structured as it is
- What alternatives were considered and rejected
- When patterns should and shouldn’t be applied
- How the system relates to the world it models
These are the questions a successor will ask. Answer them before they’re asked.
Preserve Dialogue
Treat AI collaboration transcripts as documentation artifacts. They capture reasoning in a form closer to apprenticeship observation than traditional documentation.
The transcript shows the problem-solving process: the wrong turns, the corrections, the gradual refinement of understanding. This is theory transmission material.
Embrace Redundancy
Theory is transmitted through multiple channels—prose, diagrams, examples, conversation. Redundancy is not waste; it provides multiple entry points for readers with different backgrounds and learning styles.
If one path is blocked (the reader doesn’t understand the diagram), others remain (the prose, the examples). Resilience comes from multiplicity.
Test Theory Transmission
The ultimate test of documentation is whether new team members can acquire sufficient theory to make correct modifications. This should be tested explicitly, not assumed.
Ask: can someone who has only the documentation modify this system correctly? If not, what’s missing?
Accept Imperfection
Documentation will never fully capture theory. The goal is not perfection but sufficiency—providing enough material that a motivated reader can construct a workable theory.
Some loss in transmission is inevitable. The goal is to minimize it, not eliminate it.