My experience with AI-written documentation is that, as a category, it contains just enough technical errors that more often than not I end up spending time running down confidently stated errors the old fashioned way: cross-referencing API documentation, reading code, etc. At that point you inevitably end up trying to get in touch with a human from the other team.
In other words, it's not because I don't know it's there, or I don't want to read it, it's because my priors tell me it's going to waste my time. What I end up doing is searching, finding the docs, and reading until I start to get the feeling of hallucinated factual errors.
I'm sure there's AI-written documentation in there where the authors really did a good job reviewing it, and I just didn't notice. But I've also had engineers under me lose weeks of productivity at this point because of documentation confidently presented, insufficiently vetted, that turned out to be wrong.
Like if you have an AI generate a runbook, then you better have the AI actually validate the runbook and make sure it is correct.
As an employee, I would prefer to not be stressed and as an employer, I would prefer to not additionally stress my employee on all times so that I can have them use the stress for the works which truly matter the most (which is a limited resource as an employee shouldn't be burnt out or shouldn't be given unlimited stress)
Also its probably the ethical thing to do but even rational logic dictates so in my honest opinion (not sure how much of it works exactly on documentation stuff though*)
From my experiences using AI to write documentation, if your bar is high quality documentation, yes, you do save time, but it's on the order of a 1.5-2x efficiency boost, not 10x. The AI basically saves me one draft iteration and saves me the trouble of creating charts by hand, and that's substantial, but I still need to take a fine toothed comb to the output.
The biggest issue I run into is that AI is good at the tone to address an intended audience but is not good at framing and structuring the information for said audience.
Here's the problem I have. No doubt an LLM made it faster to write those docs, but did you fully spot check it for accuracy?
A lot of people aren't which I think is why the average joe hates it. These docs can still have AI generated mistakes which are easily glossed over by a regular human.
Yes. That was just the writing portion, there is a whole team that works on publishing and proof reading and there are acceptance levels all the way up to the CISO where people validate they read it and approved of the contents. Even with that, no one cares about it.
The number of meetings where I can answer all the other attendees' questions because I'm the only one who even skimmed the presenter's docs, I swear.....
It might be that they are wordy. It might be that your readers are lazy. It also might just be they don't realize the effort has been put in to make sure the docs are of high quality.
The fascination with LLM coding seems rooted in the new ability to create something with very little effort. Unfortunately, some people do not see the trade comes at the moment you have to evaluate the output for fitness or quality.
It turns out that you often need to understand the thing pretty well in order to be qualified to determine the quality of the output. That tends to dilute time gains, unless you leave off the evaluation step.
Hi. I write lots of documentation already. I enjoy the taste of clean, fresh, accurate documentation.
Spot-check it for accuracy? I review it. The same way I would review other documentation in the past. The difference? Fewer errors and issues, and when I do find them, it's far easier to get things sorted out.
> A lot of people aren't
Correct. A lot of people aren't reviewing. Not even AI, just reviewing in general. And even when they review, they are only looking, not testing.
The difference is that before, it was a human mistake. Now it's an AI mistake, and people HATE AI mistakes. Even if the number of AI mistakes is fewer than the human mistakes.
I don't want to pretend that documentation is easy, and well-made human documentation is still far better than the best AI documentation for the most part. But... it depends on the audience and purpose. Most importantly, AI documentation is good enough for most cases, and well-made human documentation is far rarer.
That's because AIs make mistakes no human would. If you're documenting a function, you might misspell something (or orthographically spell something that should be misspelled), or confuse two functions with similar names; you won't reference a function or feature that doesn't and has never existed.
That does sometimes exist in human docs. I've stumbled on "aspirational" features in docs that never really existed but were more just intended to exist.
To me the mistakes are bad, but it's also that the docs tend to be pretty low quality IMO. LLMs tend to like to write novels where a sentence would have been better.
Listicles and those sorts of things were pretty pointless, but they didn't beat around the bush like LLMs do. I really don't exaggerate when I say I've never seen a human write like that. Like, the moment I start reading AI responses I feel the urge to skip ahead to get to the point. I probably read at most like 10% of the words they spit out.
I dont know. We have this hype cycle where ai or cars are talked about flawless or so much better then people ... years before they actually are. And then in each time we find that nah, they were not but now this time they certainly are.
And each time I read on HN about how people expect so much better from tech then from people. And usually, when you look at it, the opposite is true. Where human get criticised, tech gets tripple benefit of doubt.
Which is true, in a way, the data put down as documentation can now be calculated in seconds, and documentation is just a cache.
I actually still REALLY value the human authorship though. Not for any sweat and blood nostalgia. I find MY generated docs still have lots of little errors, sometimes pretty critical even, which I can only recognize when I have the expertise and comb through carefully on edit.
The hand written author's name was a stronger guarantee that those wouldn't exist (as much), because you could trust in their expertise, and that they had to put down every word. It's much easier to miss the slop on edit and review than in draft, in my experience.
Regardless of reasons they tell you, if no one reads your documentation, then it isn't good enough. Good documentation gets read, as long as it is good. It sounds to me like you're disillusioned, if you're not responding to the feedback, even if you sometimes have to look through the reasons people tell you on the surface.
- they don't know about it
- they can't find it when they need it
- they just don't read documentation (quite common)
- they've been burned by stale docs in the past
and I'm sure other reasons besides.And while you're right, that sometimes/usually/always the documentation isn't good enough, it's a fallacy to think that the person who has the information needed, has the skill to write docs that are good enough for people to read. And if they have the skill, they don't have the time to apply it sufficiently.
Let's face it: good docs aren't valued. Not by the organization structurally, and not by the individuals within the organization. You may say that you value it, but I bet that if someone offered to document whatever code or process to your 'good enough' level, and it would take a month to do, as a manager you would tell them to take less time (i.e. create bad documentation) and get to something more important.
People won't read documentation of something they already know (or think they know).
I see these AI docs as a net negative. The uphill battle isn’t with the average Joe, it’s for the technology to live up to its promise, or to stop selling lies.
A) this is what happens with documentation, in general.
B) as an experienced reader of documentation, I can often tell when the documentation is likely to be accurate. It's not worth reading documentation that's inaccurate. AI written things tend to be inaccurate and not worth reading.
You should be happy that your people know to ignore the work you and the boss half assed.
Once in a while someone wrote documentation - but nobody read it. Then that person was moved elsewhere in another shakeup and their documentation got obsolete. Often the documentation got obsolete even before than because the person writing it didn't maintain it (possibly because nobody was reading it?)
This to me is an anti-pattern that I see everywhere because we're still in the early stages of understanding how to adopt these things and create real agentic workflows.
Why should humans read all that documentation if they're ultimately not going to be the ones implementing it?
I see similar patterns like this everywhere, people asking questions about a PR that an engineer then copy pastes to an agents and the copy pastes back to the PR. It's obvious that humans are still in the loop in awkward places.
I've pointed this out before, but web development went through similar growing pains where we did all sorts of weird stuff because we hadn't quite figured out the patterns that work.
Right now nobody really knows what works and the tools we're using are still changing very rapidly. 6 months ago almost nobody was using agent harnesses and thinking about agents writing all of your code was preposterous. Today even the hardcore, AI-skeptic people on my team still have agents writing the vast majority of their code.
It's very clear to me that we're still stuffing agentic behavior into workflows designed for humans. It shouldn't be at all surprising that these patterns feel weird and sometimes broken. It has nothing to do with "winning over the average Joe" but rather these patterns evolving so they actually make sense.
If you did check it for accuracy then I don't understand how you compressed months of work into minutes.
Bottom line: there is no true ownership in the upper level so why should I take ownership in a product based on garbage produced documentation specs?
Having an AI write docs which are then saved and served strikes me as in the same uncanny valley as fax machines. It's a halfway step that doesn't understand the full import of a new technology. In that case, what you really want is emailing PDFs around and docusigning.
With AI documentation, let users request the docs they need on-demand.
But if it's a customer? They might not have access to Copilot at all, or whatever AI tool they use might not have access to the source code or other material used to gen the doc.
Other times it's simply for reference purposes. So if you're talking about current enterprise architecture, the AI itself needs something to reference in order to answer.
There are many reasons ultimately.
Now, if you write it with tender loving care and bake all that stuff into it, then will humans read it directly? Maybe not, but the information that their agents read and then pass on to them at least has a better chance of being correct and useful. If the success criteria for your documentation was "measurable count of human eyeballs" and not "better outcomes", your docs aren't going to be good anyway.
We do this to make sure people know what to ask for. The answer can be generated when they need it and it will be then based on the current state of things.
Edit, adding more:
If its an AI video, I don't care depending on what its supposed to be, I've seen people upset a literal meme AI video was AI, that was the point, it was supposed to be a ridiculous meme, it was on purpose, some of them aren't even as bad as the person dismissing them make them out to be.
Intellectual laziness, worse than the laziness of some people who lean way too much on AI (some people cannot have a conversation with you, without prompting a model every few minutes, its getting ridiculous).
AI has become the next stage after social media, whether you like it or not. It has taken over human interaction in ways we are still learning more about every day. All the "normies" I know use ChatGPT like they would have used Facebook.
Honest question, did you guys read it yourselves before asking the rest of the team to read it?
If they can tell it is written with AI, then the docs are slop. If you're writing something lots of people will use, don't skimp on model or reasoning level, and front load with style guides and examples.
The new key for documentation is that it doesn't need to be was by humans. Good docs are just as valuable whether people read them, or just ask an LLM and the LLM RAGs the information from your docs. The main difference you have to focus on nowadays is ensuring your documentation, even internal documentation, has good "SEO" that it gets looked up.
Even in code documentation, I just need a function block that says "DO NOT PASS A VALUE OF 2", with maybe a deeper comment that says "yea the math breaks here", instead of a 5 page discourse on why you should not pass a value of 2.
Another question is keeping those docs up to date...
In 2021 I wrote a ton of docs for outlining our deployment and various how-tos, basically just got a "cool thanks bro" for my time. People never cared, I think AI is just a convenient modern excuse.
there's also the issue that people keep switching models when their quota is used up and so at first it seems to all be in order but upon digging in suddenly it hugely diverges in tone/usefulness if it doesn't just collapse in on itself outright; making diving into documentation even more of a hassle than it was before.
even worse is that when they bring back in the previous model upon quota reset it just consumes the information from the crappier/cheaper one and errors start compounding and you want to report it and they're like "sorry we closed our public issue tracker yoy have to join our discord server" and then you have to grab the attention of extremely unwilling developers who repeatedly insist there isn't a problem until you start copy-pasting their quite frankly shit documentation en-masse.
then its "oh that's a typo; the command is correct 25 pages/sections ago so why would you believe it in this section when it's obvious that its wrong here?" like it's your fault they can't keep their goddang slop together and parse through the glaring errors.
a manual should be able to be pulled off a bookshelf (or opened if digital) and allow you to flip to the relevant page so that you can refer to it as a reference and these jerks are hellbent on blaming users for when their jank documentation looks clearly hallucinated by 3 seperate LLMs.
it is beyond frustratung.
> He and I can bang out tons of it in minutes that would have taken months before
Pre-AI, you had some work X and you were given some salary Y and you did the work in time T, now you are expected to 10-100 times X work in time T but given the same salary Y
People are worrying about their salaries and future and some people especially within Silicon valley are worried for whats to come next with AI datacenters raising electricity prices and this fear of permanent underclass and job insecurity and a terrible job market with layoffs partially because of AI spending.
If it feels stressful, its because it probably is. I imagine that some people as such might feel that reading the very same AI documentation with the same passion/care is hard.
So yes, AI has a long uphill battle in winning over the average Joe because everything in its current implementation is actively trying to screw average Joe if we think about it
but it differs depending on your incentives on your current time. In your current job, you are the one writing these AI docs in minutes, now imagine spending hours reading those very same AI docs with all the things that I have mentioned, perhaps I hope you understand why it might be more frustrating.
(also when I mean average Joe I would consider software engineer folks like us to be the one more effected than even other professions so we are the average Joe I am talking about. Its not all gloom and doom though and the average joe is split between liking/disliking it and having a nuanced opinion in the middle)
Yes, because if the whole doc is just AI slop, why bother reading?
This happens way too often at work. Someone generates a massive doc full of AI slop, unreviewed, they never even read it, and expect people to spend time reviewing it. Nope.
I've asked people about it and they seem disillusioned. It wasn't written by a human so they see no human value in it. They view it as AI writing documentation for another AI to summarize to them and then another AI to reply or comment. So they don't care or are actively repulsed by it.
I think AI has a long uphill battle in winning over the average Joe.