'The Oral Tradition That Built Software May Not Survive AI'
Published on 2026-05-31T22:15:00Z
A historian-turned-software engineer warns that "so little is ever written down" by professional programmers in a new article for Fast Company: Perhaps there's an early design doc, but then it turns out that everything was substantially revised before work began. Maybe there are a few wiki pages explaining known issues, some of which were solved a long time ago and others that have been left to molder in the codebase. Somebody might have left a comment in the code itself, but typically it's a warning not to change something or else something else will break... Software engineering has an ambivalent relationship with documentation. Everyone agrees documentation matters in theory, but in practice it's inconsistent, outdated, or missing entirely. Part of that is simple inertia. Writing documentation is usually less interesting than writing the code itself. But it's also ideological. The Agile movement emerged in part as a reaction against the heavily documented Waterfall methodology, and one of Agile's core values explicitly prioritizes "working software over comprehensive documentation." In escaping bureaucratic overdocumentation, the industry also normalized underdocumentation. High turnover at software jobs always brings "a constant drain of domain knowledge." And he's he's skeptical that generative AI will be able to fill in those gaps: [H]aving it generate documentation on the codebase itself might sound like a solution to the absence of other written information. LLMs can certainly summarize code back to you. But hold up with that idea. Beyond hallucinations, there's a deeper problem: Writing documentation is itself part of the thinking process. Whether I'm writing history or software, putting an approach into words helps refine it before I sink hours into implementation. Documentation also captures intent. An LLM may be able to summarize what a codebase does, but it cannot reliably explain why a developer chose one approach over another, or what trade-offs shaped that decision... An LLM can read code that I've written. It might even scan a large codebase and accurately summarize what it's doing. But it can't assess authorial intent. Thanks to long-time Slashdot reader smooth wombat for sharing the article.
Published on 2026-05-31T22:15:00Z
A historian-turned-software engineer warns that "so little is ever written down" by professional programmers in a new article for Fast Company: Perhaps there's an early design doc, but then it turns out that everything was substantially revised before work began. Maybe there are a few wiki pages explaining known issues, some of which were solved a long time ago and others that have been left to molder in the codebase. Somebody might have left a comment in the code itself, but typically it's a warning not to change something or else something else will break... Software engineering has an ambivalent relationship with documentation. Everyone agrees documentation matters in theory, but in practice it's inconsistent, outdated, or missing entirely. Part of that is simple inertia. Writing documentation is usually less interesting than writing the code itself. But it's also ideological. The Agile movement emerged in part as a reaction against the heavily documented Waterfall methodology, and one of Agile's core values explicitly prioritizes "working software over comprehensive documentation." In escaping bureaucratic overdocumentation, the industry also normalized underdocumentation. High turnover at software jobs always brings "a constant drain of domain knowledge." And he's he's skeptical that generative AI will be able to fill in those gaps: [H]aving it generate documentation on the codebase itself might sound like a solution to the absence of other written information. LLMs can certainly summarize code back to you. But hold up with that idea. Beyond hallucinations, there's a deeper problem: Writing documentation is itself part of the thinking process. Whether I'm writing history or software, putting an approach into words helps refine it before I sink hours into implementation. Documentation also captures intent. An LLM may be able to summarize what a codebase does, but it cannot reliably explain why a developer chose one approach over another, or what trade-offs shaped that decision... An LLM can read code that I've written. It might even scan a large codebase and accurately summarize what it's doing. But it can't assess authorial intent. Thanks to long-time Slashdot reader smooth wombat for sharing the article.
Read more of this story at Slashdot.
Comments
Post a Comment