'The Oral Tradition That Built Software May Not Survive AI' (fastcompany.com)
- Reference: 0183495768
- News link: https://developers.slashdot.org/story/26/05/31/226253/the-oral-tradition-that-built-software-may-not-survive-ai
- Source link: https://www.fastcompany.com/91549609/the-oral-tradition-that-built-software-may-not-survive-ai
> 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 " [2]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 [3]smooth wombat for sharing the article.
[1] https://www.fastcompany.com/91549609/the-oral-tradition-that-built-software-may-not-survive-ai
[2] https://agilemanifesto.org/
[3] https://www.slashdot.org/~smooth+wombat
Everybody Hates Documentation (Score:5, Insightful)
It usually goes to the lowest-ranking person on the team or the one everyone's trying to keep away from actual coding.
It remains worth the effort to write a novel around your code - not just what you did and why you did certain things a certain way, but the meta-reasons. The more those who come after you understand, the easier it is for them to figure out and maintain your code. It also tends to focus you more on writing good code, because you don't want to document, "Well, it looked good enough and didn't immediately produce errors and I'm tired of this and want to move on".
AI code? Well, AI should be very good at generating plain-language documentation of 'what', but it is absolutely going to fail at 'why'.
Re:Everybody Hates Documentation (Score:5, Insightful)
> It remains worth the effort to write a novel around your code - not just what you did and why you did certain things a certain way, but the meta-reasons
I don't know if I'd go full novel, but I try to write my code so intention and implementation is clear with commentary to fill in the gaps. The farther things stray from that and/or the weirder the code gets, the more documentation I leave, especially if, for some reason, it needs to be like that.
While I enjoy the old saying, "Real programmers don't document 'cause if it was hard to write, it should be hard to understand.", I don't follow the practice; the harder it is to write the more documentation it needs. I also try very hard to be consistent in my implementations, style and commentary and have had several co-workers say they can tell it's my code just by looking at it. I learned that over time, mainly because I looked at my own earlier code at some point to reuse it and had trouble figuring out what I had done and why. I thought "Not cool, me."
So, I don't mind documentation, but will say that management is often loathe to allocate enough time for it to be done/maintained well.
Re: (Score:2)
> AI code? Well, AI should be very good at generating plain-language documentation of 'what', but it is absolutely going to fail at 'why'.
It could just say that it's some bullshit that someone in management wanted to try and it would be right enough for the "why" at least 90% of the time. This also partially explains why no one wants to document. If what they're making has a good chance at getting thrown out why spend time documenting any of it?
Re: (Score:2)
That might be why a feature exists, or maybe even why a particular paid library was chosen instead of another. That doesn't explain why the code is written the way it was, which is the point of documentation. Why the feature exists is the realm of the PRD, not the design doc.
Re: (Score:2)
I am reminded of some source code for a company-specific program that I saw in the late 1990s. I don't remember why I was perusing it, as I was in IT and absolutely not a developer. But I remember being tickled at one of the comments before a block of code. It was something like, "I have no idea why or how the following code works. But every time someone tries to change it, everything breaks, so please don't touch it."
But it can't assess authorial intent. (Score:4)
Neither can another human being. If you want that information preserved, it has to be done by the original author. The same is true for other forms of information presentation (books, etc.).
Re: But it can't assess authorial intent. (Score:2)
And even then many companies today protects their 'intellectual property' so much that writing down documentation might be seen as harmful.
Intent is the most important thing (Score:5, Insightful)
Something critical to note: intent is the most important thing to document when it comes to software. You can see what it does by reading the code, that's straightforward. What I need to know most, both when writing software and maintaining it later, is why it's doing that. What's it supposed to be doing? Why is it doing it in that way? What were the alternatives and why weren't they chosen? How is it supposed to be used by code that calls it? An LLM can't generate any of that just from the code.
This is why traditionally software libraries have had two separate pieces of documentation: an API reference that details every call and it's arguments and results, and a user's guide that lays out how and why to use the library.
Re: (Score:2)
Yes! Particularly in languages with rich semantics and a tradition of meaningful identifiers, the primary focus on documentation where I've worked has been on 'why' rather than 'what.' In Ada, which separates specification/API from implementation, the comments in the spec explained what the package did (including errors/exceptions), and the comments in the body concentrated on capturing what was not obvious -to a maintainer- in the code. Ada culture strongly emphasized maintainability, and that was empha
Re: (Score:2)
Unfortunately, when they are separated like that each half becomes nearly useless. They need to be merged, though with clear demarcations so you can skip a part that isn't currently relevant.
Re: (Score:2)
Please, no. Often when writing code I need the API reference and only the API reference. I know what I want to do and how to do it, I just need a quick check of the exact order of arguments or exact symbol names. I don't need to try to sift that out of commentary. Likewise when I'm learning how to use the library I'm more interested in the overall view. I don't need to know the exact names of the options for a call, only what the options are for. I expect the code in the user's guide to be accurate, but I d
Intent is also the hardest thing (Score:2)
Yes, and that's something that LLMs are, in my experience, extraordinarily bad at.
We fired a new hire last year who was clearly just delegating everything to an LLM. When I asked why he did something the way he did, he responded with a list of obvious LLM hallucinations. Bizarre "requirements" that nobody ever asked for.
If you ask it for reasons, it will give you reasons. Like when RFKjr asked for medical research to support his absurd conclusions and it hallucinated a bunch of bogus citations.
It'll be inte
What a funny thing to say (Score:1, Troll)
What a funny thing to say about something that is literally all text. Match up the code itself with the commit message and the ticket that caused it to happen - we work in the most documented business there is.
If you don't force/write good commit messages then you get what you deserve.
If you don't force/use good issue tracking then you get what you deserve.
In general, AI now composes my commit messages. Then I delete 2/3 of it. Sometimes I'll touch it up a bit. So it is helping our process...
For every l
Its called Institutional Knowledge (Score:2)
Its called Institutional Knowledge, and it hits pretty much any industry or trade that requires non-trivial skill.
Programming oral?Yes, and it is a thought process. (Score:3)
And if you need to relay any information you make a note(for yourself) or talk it over(development group).
But if you are a programmer, the truth is, a programs code is the documentation. And you read/compile/run/tweak the code and that tells you what you need to know.
I have walked into projects blind where the client had the executables. Along with what they thought was the developers source but no one could get anything to compile.
It was like archeology and walking into a failing project as an outside contractor often is.
Real programmers don't document (Score:3)
If you can't read code, you shouldn't be programming!
Kind of like regular history (Score:3)
> Everyone agrees documentation matters in theory, but in practice it's inconsistent, outdated, or missing entirely.
There's a lot of this in "regular" history too. A whole lot of what happens is never written down, or is subject to revised memories, or is slanted by ideological points of view.
On the other hand, is it *really* necessary to have detailed records of all code that is written, no matter how insignificant? If it were, businesses would demand it. Ask anyone who writes code for a company that must comply with SOC II.
If the software doesn't document itself (Score:2)
It's probably not well-written.
Who on earth reads the documentation for Google.com, or GMail, or Word, or Excel, or any widely-used software? If you are using one of these, and you can't figure it out from the UI, I'd argue that the UI is messed up and should be revised.
the inverse (Score:3)
Something I've been toying with lately, LLMs can not only analyze the codebase, but also the git commit history and log messages. The developer intent IS there, it IS documented, but not in traditional documents that are easy for humans. These are instead in a form that is easy for LLMs to consume which then can summarize them back out into human readable documents. I've been using this for the exact reason described, I inherited several codebases after employee turnover with no chain of custody to bring forward that tribal knowledge directly.
AI does it better than most programmers (Score:5, Interesting)
As an old-school programmer, I've been impressed with what AI can do. Unprompted, it will insert comments into the code referencing the context of our chat; e.g.
// Cache lookups in an interim map to avoid O(N^2) bottlenecks in the nested loop below.
And it will provide even more documentation and reasoning if requested in the instructions. Meanwhile I've encountered hundreds of devs in my career who couldn't or wouldn't document any of their work. I'm not surprised that AI is proving so effective at replacing them, because AI is very happy to do the so-called "boring" work of documentation and test case writing.
Re: (Score:2)
Except for the bit where it does that caching for a loop where each lookup only occurs once. Because everybody caches lookups, so that must be the right thing to do (it's the most likely thing to happen) in a case where the cache is never used. Riiiiight...
Re: AI does it better than most programmers (Score:2)
I think you hit the nail on the head. AI writes better comments than most humans. Where everything falls apart is when the user documentation leaves behavior unspecified. When I test something I read the docs to see what it should do. It's very easy to miss subtle behavior change because something was never documented.
We're all gonna die! (Score:2)
Seriously though Dennis Ritchie died in 2011. Ken Thompson is 83 years old! The oral tradition suffers from this fundamental problem, but a 64 bit linux container running a language model might last for many centuries!
Shitty code (Score:2)
Well written code is self-documenting, specifically because once you start putting documentation somewhere else, you start getting a divergence in truth. And I'm not talking about leaving comments in the code - that's also documentation, as anyone who has had to reconcile business processes with code can attest upon discovering that the comments and the code also don't agree with each other. (This is where I try and sell people on having detailed commit messages, and then realize that they're all going t
So pivot (Score:2)
I told my partner straight, "if our oral tradition ever dies .. you're out!".
Now I'm trying my hand at a new tradition.
actually (Score:2)
.. But it can't assess authorial intent.
idk if you're using the same popular code-writing tool that i am, but it's way better than human programmers at documenting the whys in addition to the whats and hows. additionally it's a snap to have it curate the architectural and design decisions currently being introduced. the oral record going forward is going to be --much-- more robust than in the past. as far as assessing the authorial intents of existing code, it's pretty good at that too.
i don't love
AI can generate new code, but can't maintain it (Score:2)
Here's the text reformatted for Slashdot's plain-text style — no tags, just spacing and ASCII conventions:
---
At least, that has been my experience.
Prompt I did today:
Is AI code generation excellent at maintaining software, keeping backwards compatibility, handling edge cases, and minimizing regressions?
--- Claude response ---
Short answer: not really -- at least not yet, and not without significant human oversight. Here's an honest breakdown:
Where AI code generation falls short on maintenance
Backwards
AI is the bogey-man (Score:2)
... that modern system administrators will use when they want to tell their children scary stories. But this isn't a new problem, and the posited idea that before AI there was some "oral tradition" that rendered this a non-problem is laughable.
The past few years, I've had to deal with a lot of code + configuration files that are poorly documented or not documented at all. Some of them are occasionally commented... but often with references to non-existent entries in the team's wiki. I'm sure my predecessors
"The reason why" lost in final work product (Score:1)
Look at most instruction manuals. Look at most architectural blueprints. Look at a schematic. Look at a recipe book. Look at most other "work products" that amount to human-readable instruction manuals.
Now look for the "why". "Why are we doing this in the first place." "Why did we do it this way vs. the various alternatives." Etc.
Sometimes you will see the "why" but most of the time you won't.
At least code has the advantage of having a mechanism to put the documentation near the relevant portion of th
I'm I'm skeptical too. (Score:5, Interesting)
Maybe AI can help with the archaeology that has to happen whenever new hands discover a code base.
Re: (Score:2)
AI does poorly with the history of the software it generated itself. Its not uncommon to mention some special consideration in one session, and in a different future session require some non-trivial reworking that then ignores that special consideration it is now unaware of. Its common to be in a one step forward / one step backwards situation for multiple iterations. Each time something old breaking while the latest problem mentioned is fixed.
Re: I'm I'm skeptical too. (Score:2)
Of course, if the AI has a gigantic context window (it may not yet, but I'm sure it will), it could have the entire code base "in mind" at once (as though every page of a novel is fresh in yours).
With such a window, it could see where such (mal?)adaptations are used everywhere in the code.
That can't work every time, but it might be a useful talent.
I'm hard-skeptical about AI as a do-it-all coder, but as a tool, I'm certain it's profoundly useful in the right hands, right situation.
Re: (Score:2)
I think a giant context is not going to be the answer. It's just got too many problems. Better will probably be parsing the context into connected pieces, and at a different level assembling the "lemmas" into "theorums". (Yeah, those aren't quite the right words, but I'm not sure the right words exist, and that's the analogy from math proofs. Code library isn't the right concept as the "lemma" will often be quite specific to the current task.)
Re: I'm I'm skeptical too. (Score:2)
This is very old in AI time, but it fascinated me to see how a game could build a self-consistent world by keeping an entire book in context.
[1]https://thelongcontext.com/ [thelongcontext.com]
[1] https://thelongcontext.com/
Re: (Score:3)
The current state of AI for this (I recently started working on a new project), is AI can find and summarize topics. But it has poor temporal understanding, it doesn't understand that documentation is out of date or that old Slack discussions or Confluence comments that were never incorporated into the documentation and code are irrelevant. Using it as a tool to sniff out potential trails seems to be about all it can do. From there, you as the human being have to investigate AI's claims and resolve the conf