Forgot your password?
typodupeerror
AI Programming

'The Oral Tradition That Built Software May Not Survive AI' (fastcompany.com) 86

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.
This discussion has been archived. No new comments can be posted.

'The Oral Tradition That Built Software May Not Survive AI'

Comments Filter:
  • by jddj ( 1085169 ) on Sunday May 31, 2026 @06:23PM (#66168576) Journal

    Maybe AI can help with the archaeology that has to happen whenever new hands discover a code base.

    • Re: (Score:3, Interesting)

      by drnb ( 2434720 )
      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.
      • 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.

        • by HiThere ( 15173 )

          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.)

    • by OrangeTide ( 124937 ) on Sunday May 31, 2026 @08:20PM (#66168748) Homepage Journal

      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 conflicting information.

    • by AmiMoJo ( 196126 )

      I've used it for reverse engineering and was surprised how well it did. I decompiled some old Amiga game code back into assembler, but without any debug info so it was a complete mess. I started with Ghidra, but ran out of steam with it, so just threw the decompiled assembler at Gemini and asked it what the format of some files was. It figured it out and got the correct answer, bar a couple of minor issues.

      Next time work asks me to do something with an ancient codebase I didn't create, I might well try gett

    • by coofercat ( 719737 ) on Monday June 01, 2026 @09:10AM (#66169256) Homepage Journal

      With Spec Driven Development, the documentation is the "source of truth" and the code is just an expression of it. As a developer, you have to review the code, but if it needs modification, you modify the specs - not the code.

      So in future, developers could be spending their time editing markdown descriptions of things instead of actual code. They're still going to need to know how to code though, because they need to review what is produced, but they won't need to spend the time to get the syntax just right - AI will have done all of that.

      If (and it's definitely still an "if") SDD proves out to be a better way to write software (at least in certain domains), then it will indeed do away with the verbal story telling. If it's not part of the spec, it isn't part of the code. Whilst spec writers might be as slapdash as Jira ticket writers, there will have to be at least some mention of every "side conversation" that ever took place, if it's part of the end product.

      There's no magic though - it's still garbage in, garbage out. Keeping the quality of those specs up is the subject of most of the research in this area right now. Likewise of course the model makers are trying to produce better quality code for ever more vague prompts. It remains to be seen if any of this is truly successful, but already today it is a way to get some software written - and crucially also get some high quality, up to date software written for it too. I'm sure there are people studying this sort of thing, but it's believed that the output of SDD is faster (maybe cheaper?) than humans hand-writing it all.

  • by Baron_Yam ( 643147 ) on Sunday May 31, 2026 @06:24PM (#66168578)

    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'.

    • by fahrbot-bot ( 874524 ) on Sunday May 31, 2026 @07:04PM (#66168640)

      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.

      • by Ocker3 ( 1232550 )
        Time spent figuring out old code is a problem for Future Manager!
      • 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.

        This part. I feel like it's ALWAYS this part. No time for documentation/keeping it up-to-date, no time for desperately needed custom tooling even with huge user buy-in, no time for anything you can't immediately sell to someone for a quick buck.

    • 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?

      • by AuMatar ( 183847 )

        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.

    • 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."

    • by allo ( 1728082 )

      It at least excels at the "How". Have you tried one of the IDE integrated agents in "ask" mode? You ask "How and when is X called and what are the side effects", allow it to read all workspace files without asking and let it work. When you come back five minutes later, you get a free text description, a table and some flowcharts with the answers. Of course you can also ask follow up questions.

      They why may or may not work, just as for humans. If the code base is ... lets say suboptimal, then anyone reading i

    • If your company relies on "oral tradition" to maintain documentation, then your company may not survive with or without AI.

      "Oral tradition" is the engineering process of knowledge being lost. That is to say it's not engineering.
  • by Retired Chemist ( 5039029 ) on Sunday May 31, 2026 @06:28PM (#66168584)
    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.).
    • by Z00L00K ( 682162 ) on Sunday May 31, 2026 @09:43PM (#66168824) Homepage Journal

      And even then many companies today protects their 'intellectual property' so much that writing down documentation might be seen as harmful.

    • by gweihir ( 88907 )

      That is untrue. Smart humans can recover authorial intent, at least partially.

      • Absolutely! It's not even that hard to understand why. The company bottom line depends on matching the code with the business logic, and the incentive structure for the employee coder is aligned. A highly paid programmer thinks about what is actually needed and develops the requirements in accordance. If another highly paid programmer joins up, he will think about what is actually needed by the business too and converge on equivalent requirements. None of this makes sense to a junior programmer or a code co
        • by gweihir ( 88907 )

          Indeed. But seeing how my comment got moderated down, I guess a lot of people are deep in AI psychosis now and cannot tolerate any criticism of this new golden calf.

    • by allo ( 1728082 )

      Tell teachers who grade lyric interpretation. "That's not how the author meant it!" Sure?

  • by Todd Knarr ( 15451 ) on Sunday May 31, 2026 @06:34PM (#66168594) Homepage

    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.

    • 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

    • by HiThere ( 15173 )

      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.

      • 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

    • by Tschaine ( 10502969 ) on Sunday May 31, 2026 @09:53PM (#66168828)

      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 interesting to see whether the frontier labs are able to improve on the current state of the art. The information might exist in the company, spread across emails and chats and random docs, so it's not impossible. But deducing intent does sound harder than writing code.

    • by gweihir ( 88907 )

      Indeed. And if that part is missing, good luck with maintaining that software or debugging problems.

      Just another reason why LLMs are not the answer to software creation.

  • 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, and it hits pretty much any industry or trade that requires non-trivial skill.
    • by gweihir ( 88907 )

      C-levels do not understand institutional knowledge. That is why they are currently firing large numbers of people that have it and were that will be lost. Enterprises die that way, even if it usually takes a while.

      • by drnb ( 2434720 )

        C-levels do not understand institutional knowledge. That is why they are currently firing large numbers of people that have it and were that will be lost. Enterprises die that way, even if it usually takes a while.

        That's odd, Business Schools specifically teach that organizations tend not to last forever, or at least not dominate forever. That loss of institutional knowledge is one of the classic contributing factors to self destruction.

        You know what else Business School's teach? That you get what you reward, even if people know it's the wrong thing. This happens at the CEO level too. Most CEOs are not founders, they are just temporary job holders. They are rewarded for maximizing rewards to investors, to having a

  • 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.
  • by Tony Isaac ( 1301187 ) on Sunday May 31, 2026 @07:07PM (#66168652) Homepage

    If you can't read code, you shouldn't be programming!

    • Yes, and no. Decent programmers should be able to read "Normal" code; code that is clear, concise, and well structured. And then you have code that was written in reality; and then grafted on; and then "refactored"; etc.

      Which leads to an interesting question: if all of this code was "reviewed" after each iteration, how'd it get so badly warped?
      • Yeah well that spaghetti code that was refactored multiple times...I guarantee that guy didn't write documentation either. And even if there *were* documentation, do you think the code would match? Probably not. So we're back to reading code again.

        Thankfully, AI is actually helpful in this, it can often trace existing tangled code pretty well.

    • If you can't read code, you shouldn't be programming!

      If you can't provide context for the program that you wrote, then you shouldn't expect anyone to try and read your code.

      • For sure. Most companies can't be bothered with actual requirements! They want you to just "make something work."

    • by allo ( 1728082 )

      It was hard to write, so it should be hard to read!

  • by Tony Isaac ( 1301187 ) on Sunday May 31, 2026 @07:12PM (#66168660) Homepage

    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.

  • 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.

    • Re: (Score:2, Informative)

      by Anonymous Coward

      You figured out how to do arrayformulas just from the 'fx' box? Unbelievable.

    • by gweihir ( 88907 )

      What a stupid comment. Software does not exist in isolation. It interacts with the real world and other software. And that part is the really critical one and it cannot be extracted from the code.

      • Who said anything about extracting things from code? My comments were about the user interface, not the code.

        • by gweihir ( 88907 )

          The user interface is equivalent functionally (in the strong, formal sense) to a part of the code, because it is right in there. And no, the UI will NOT give you that information either.

          Seriously, are you stupid or what?

          • Yes, I'm stupid, just ask my wife!

            Now that we've gotten that out of the way...

            My whole point is that strong, formal documentation is usually not needed. Programmers hate doing it because it's generally useless. Nobody reads it, and nobody abides by it when they write new code. There's a reason for this. Writing software is more like art than science. Painters don't write detailed specs describing what they are painting, they make the painting such that it can be perceived and appreciated without such docume

  • the inverse (Score:5, Interesting)

    by darkain ( 749283 ) on Sunday May 31, 2026 @07:15PM (#66168670) Homepage

    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.

    • I save all of the plans I/AI creates (even for small changes) and attach to the user story. Then if there is a bug anyone can load plan into context to understand what was done. The documentation is 100X better now with AI.
      • by allo ( 1728082 )

        They can be VERY verbose to read. But ... we have AIs to summarize them, or to answer targeted questions. Let the agent read 100 plans and then explain how and why the feature evolved.

  • by mykro76 ( 1137341 ) on Sunday May 31, 2026 @07:37PM (#66168694)
    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.
    • 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...

      • by twdorris ( 29395 )

        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.

        You're so clever. I'm impressed. Except for the bit where the comment LITERALLY SAYS nested loop. Which sure suggests to me that inner loop being optimized is not done once. It's probably being done once per, I dunno, each outer loop iteration. And probably the method in which this nested loop exists is called more than once I suspect.

        You wanna be all Mr. Smartypants and poo on all things AI, fine, go for it...but at least put some damn thought into it beyond the basic coder level of awareness AI is go

    • 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.

  • 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!
  • 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

  • I told my partner straight, "if our oral tradition ever dies .. you're out!".

    Now I'm trying my hand at a new tradition.

  • by cathector ( 972646 ) on Sunday May 31, 2026 @09:39PM (#66168816)

    > .. 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 this situation, and i mourn the craft i've spent several decades honing, but it credit where it's due.

    • by kwalker ( 1383 )

      Having seen new developers turn AI agents loose on existing code bases several times now, I can tell you that yes, "AI" is "good" at writing up excuses/justifications for what it's doing. However I've also seen in all these cases, the code is just wrong, or it's technically correct, from the basic 100 foundational level, but it's still falling straight past the existing library code and methods to do exactly what it was asked to do, and instead doing the 10-year-old workaround kludge from before that librar

  • 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

    • by allo ( 1728082 )

      What you're basically saying is, that you need documentation for AI to be good at maintaining it. If you already use AI or have documentation you're fine. Instruct the AI to keep it up to date. Otherwise maybe ask the AI to document the status quo and possibly add a plan for refactoring. Current AI is limited by context, so it is very good to keep less verbose information than you code base. Have understandable documentation about the how and why and it does not only help AI.

  • ... 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

  • 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

  • Not sure I agree with all the "humans are superior, therefore x" logic. Yes they are superior except I think in being able to read tons of code without your eyeballs shriveling up. I think AI can figure out authorial intent pretty well in that situation. Also, since we now have to write much more detailed specs in order to get AI to build things to any reasonable level of quality, there are a lot more readme and technical design files in markdown nearby. If those could just be deployed it would be great. In

  • Going from bits/OP-code to OOP and Functional Programming easily happen on its own in a single individual lifetime and career if the hardware is there and available. Many people doing programming in the 80ies or eariler discovered some form of OOP on their own just by writing code. The first serious refactoring of the first seriour program usually leads to OOP all by itself. I clearly remember discovering fundamental principles like higher PLs, APIs, OOP, information hiding, state management, event / messag

  • This is so wrong and backwards that it's surprising that it ended up on /.

    The reason we have an "Oral tradition" is because we're lazy. Everyone knows this is the bad way to do software and we should have documentation on many different levels.

    "The code is the documentation" is the standard phrase used. But good developers know this a bad excuse and always say it as a half joke. Not completely, because there is a truth to it, of course. But using the code as the only documentation is just plain wrong.

    The pr

    • by PPH ( 736903 )

      About 30 years ago, I worked with a system that would take documentation*, written by engineers, and automatically generate executable code. It worked. But it was pooh, poohed by our CS people. Because of their AI-completeness [wikipedia.org] criteria. But it worked.

      Two things killed it off: It was written by a couple of mechanical engineers. Who couldn't possibly understand how to write code (according to our CS people). And when the push came to move everything from *NIX systems to Windows, Microsofts consultants respon

  • The book I wish I'd started from is How To Design Programs [htdp.org]. While it uses a dialect of Lisp, Racket, the key ideas are applicable to all programing langues.

    Essentially, it encourages designers of anything to "think before you ink". In the case of software, first write a "Signature, Purpose Statement, Header" which expands to: State what kind of data the desired function consumes and produces. Formulate a concise answer to the question what the function computes. Define a stub that lives up to the signature.

  • I've been coding for well over 50 years and I am still surprised if I see a comment in code that indicates the intent of the code following the comment. The intent not the how of the implementation is what someone new to the code can really benefit from when time comes to modify it. I think it's hopeless to expect that will change, and as the article says, having AI (or a warm body) add comments based on what the code does is more or less useless.
  • I get the impression that many of the commenters here are still writing their own code, which they may or may not document. And if they do the documentation quickly becomes obsolete. Like it or not, that mode of working is now obsolete.

    These days the savvy programmer starts out by describing what he wants and tells the AI (LLM) to generate a detailed proposal. When you're satisfied with that you tell it to create a phased implementation plan with milestones. The AI works through the plan step by step. After

  • IMHO, intent is the design specification that is created before the first line of code is written, and lays out clearly what needs to be done and teh intended purpose and outputs. It then gets updated everyone something is changed. However, like unicorns, it is a mythical creature beloved by all but seen by no one.
  • 1. Self-documenting code (which AI doesn't do)
    2. As opposed to "comments considered harmful", a paper from, IIRC,
                1968. I mean, the fumes from the line printers printing all that
                  additional text...
    3. Another reason to despise Agile.

  • I learned most of what I know today from FAQs and how-to documents
    The WHY of changes are usually documented.
    I learned VERY little from was RFCs and specs.

    I can point to a widely disseminated piece of code that very faithfully implements an RFC very carefully specified behavior... And in even slightly complex environments causes issues, proving "broken by design" is very real.

  • "If you can't read this code, you don't belong here". I've done my best to document under pressure, having survived waterfalls and agile-like ("we're not doing it right" say the scrum masters). However, there's nothing like code walk-throughs with juniors and seniors to pass the relevant information and getting challenged and having to explain why this works properly although it's just a bit outside some outdated coding standard. I've written tons of documents with proper grammar and drawings and picture
  • It used to be managers demanding some kind of design document before implementation took off. That means nice pictures they can show to middle management to prove that we're actually thinking and not monkeying around with code until we get a working ball of spaghetti we can ship to production so it can run out of memory and fall over. This documentation has boxes with arrows pointing to the obvious integrations and dependencies needed to make the thing work, and the system itself is just a box with in that

  • Imagine this: you're trying to build a Linux-based appliance. You run up against some problem and Google is no help. So you go to some forum and ask how to solve it. Some smarty pants says "Figure it out for yourself! You want to stand on the shoulders of giants!" Um, no, I don't want to hire a gatekeeper such as yourself for a stupid amount of money to answer one question.

    AI is the next stage in the democratization of information in the same way that Google and the Internet were to expensive universiti

"Probably the best operating system in the world is the [operating system] made for the PDP-11 by Bell Laboratories." - Ted Nelson, October 1977

Working...