datakan
4 hours ago
The uncanny valley is happening with enterprise work. My boss is in love with Copilot writing documentation that we've sorely needed for many years. He and I can bang out tons of it in minutes that would have taken months before. We do this and then no one reads it.
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.
munchbunny
4 hours ago
> We do this and then no one reads it.
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.
tcoff91
3 hours ago
1-shotting documentation with AI is a bad idea. You then have to have multiple verification passes to have any chance of it being worth anything.
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.
ink_13
3 hours ago
The step that a lot of people leave out is the revising: it is worth the human hours to go over the outputs of AI for this kind of thing with a fine-tooth comb to make sure it is usable, readable, accurate, etc.
Imustaskforhelp
3 hours ago
I would then have to wonder if all the time saved in the first place at all. I have heard anecdotes of verifying AI output to be more time-consuming and generally even more painful/stressful than doing the whole work yourself perhaps.
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*)
cogman10
4 hours ago
> He and I can bang out tons of it in minutes that would have taken months before
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.
datakan
4 hours ago
> 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?
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.
glaslong
4 hours ago
In general people always seem to want documentation, so they can pull it up exactly when they need it, but will do anything to avoid actually having to read it until that singular moment.
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.....
cogman10
4 hours ago
Yeah, IDK what to tell you then. Sometimes docs just go unread. There's a reason why "RTFM" is a meme.
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.
jrochkind1
4 hours ago
In this case, effort has _not_ been put in to make sure the docs are of high quality, and the potential readers know that, which is surely relevant.
fluoridation
4 hours ago
I assume by "proof-reading" you don't mean just checking that the text doesn't contain spelling mistakes or is incoherent, but including that the content is actually correct. If your people actually invest that much into documentation, what the point of the LLM? Isn't the actual writing part like 10% of the total effort expended, in terms of man-hours?
gorjusborg
4 hours ago
Ignoring how a thing was created, is it useful to me (or anyone)?
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.
jasonlotito
4 hours ago
> 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?
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.
fluoridation
3 hours ago
>Now it's an AI mistake, and people HATE AI mistakes. Even if the number of AI mistakes is fewer than the human mistakes.
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.
cogman10
3 hours ago
> 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.
fluoridation
3 hours ago
Yeah, that's true. I don't understand why they do that. People don't write like that, we're pretty economical. It's not even that they're repetitive to emphasize a point, they just engage in horrific circumlocution. Is it, like, that the facts of the input only percolate through the network when they emit a token, so they only "think" when they're outputting something? I don't know if that's it, but that's what I would think if I caught someone writing like this, that they're writing faster than they can think, so they fill the void with vacuous noise.
cogman10
3 hours ago
My non-serious assumption is that they prioritized the classic writings of 1800s authors like Johann David Wyss in their training. These authors were paid by the word, which resulted in long pointless chapters in their books just to milk money out of the printers.
watwut
3 hours ago
> 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 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.
groestl
4 hours ago
> It wasn't written by a human so they see no human value in it.
Which is true, in a way, the data put down as documentation can now be calculated in seconds, and documentation is just a cache.
glaslong
2 hours ago
Yeah, if a human didn't write it, I might as well have generated it myself. And it'll be better tailored to the information I'm seeking.
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.
unicornops
4 hours ago
The truth is the documentation never had any value.
icedchai
4 hours ago
AI documentation is also often incredibly verbose. It makes it difficult to see the forest through the trees. I am often repulsed by the README.md in many "AI generated" projects.
embedding-shape
4 hours ago
> no one reads it. [... ] they seem disillusioned
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.
saulpw
4 hours ago
There are many reasons people might not read your documentation, and "it isn't good enough" is only one of them. To wit:
- 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 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.
krisoft
3 hours ago
Maybe. But also if the thing was not documented for years, then maybe the users learned how to use it without documentation? Or at least how to get what they need done.
People won't read documentation of something they already know (or think they know).
al_borland
4 hours ago
My co-worker has been using Copilot for his readme files. It would be better to have nothing at all. Without a readme fill I would go to the code to find what I need, or ask him. With the Copilot readme file, I get a bit excited that I will save some time, read it, think some things sound a bit off, go to the code, find that the readme is a fabrication with no basis in reality, reach out to the co-worker to tell him what happened, wait for him to manually write a proper readme, and then I can carry on with my work.
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.
toast0
4 hours ago
> We do this and then no one reads it.
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.
giantg2
4 hours ago
Most people weren't reading documentation when it was written by humans. The low value status of documentation is well supported by the fact your workplace put it off instead of prioritizing it.
datakan
4 hours ago
You're not wrong, but we've had a huge shake up internally and all of the people that used to complain about not having it are now in a position to create it and approve it. They just don't care anymore because now its just AI.
bluGill
4 hours ago
Those shakeups have happened many times over the decades. Nothing changed.
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?)
roadside_picnic
3 hours ago
> We do this and then no one reads 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.
ignorantguy
4 hours ago
I am seeing the same thing. People are even sending slack messages using cursor or claudecode. You post a PR or ask a question, I get a long response that was not written by a human. Uncanny valley it is.
khuey
4 hours ago
Unless you've checked it for accuracy why would I read your AI-generated documentation when I can ask my AI (which in a month or two will be a newer, better model than what you used to generate that documentation) to read the code and summarize it for me?
If you did check it for accuracy then I don't understand how you compressed months of work into minutes.
luisgvv
2 hours ago
Average Joe here - The problem is when your boss/PM is also an average Joe that bangs a 200 page doc and he doesn't even care to review properly leaving lots of gaps, redundant details and doesn't even know the rationale behind the decisions in the document.
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?
michaelchisari
4 hours ago
"If You are Asking for Human Attention, Demonstrate Human Effort"
munificent
4 hours ago
Why bother having Copilot write documentation ahead of time? For the people who need it, they can just ask Copilot the one targeted question they have in that moment and it will serve them a textual answer to exactly that.
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.
alistairSH
3 hours ago
Might depend on the target reader of the doc... if it's another engineer consuming APIs or libraries, yeah, they can just use Copilot or other to answer in real-time, no published doc needed.
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.
datakan
3 hours ago
A lot of times its for audit purposes. You have to show a mature documented program etc.
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.
jollyllama
4 hours ago
Probably because you and your boss have valuable context and historical knowledge about why things are the way they are, and this is of course lacking when you pawn the task off to Copilot.
nlawalker
3 hours ago
Yes, this right here. Generated content that's based on sources that readers already have access to has no value beyond what they can ask an LLM to generate themselves.
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.
bcrosby95
4 hours ago
If someone writes content with AI, I don't exactly see a problem with people using AI to synthesize the content. It's a good default.
changs
4 hours ago
If the documentation is generated by AI, often it's better to just share the prompts used, instead of the documentation.
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.
giancarlostoro
3 hours ago
AI fatigue is one thing, what I'm seeing mistaken for fatigue is AI prejudice, whereby they don't care if it's high quality output, you could have had literal human experts certify it, because it is AI, they just call it slop and walk away. There is no standard or reasoning with these people about AI at all, they've written it off in the most ignorant of ways. I care about the quality of the output, and if its been human vetted.
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.
Reddit_MLP2
3 hours ago
yup, ALMOST correct documentation, but using 10-20x the amount of words needed to actually document. Is it better than nothing? probably? Much of it is really hard for a human to read though. So if the purposed us to document what the AI did for a future instance of an AI, sure, but I don't see the current tech replacing technical writers in the short term.
mchaver
4 hours ago
> He and I can bang out tons of it in minutes that would have taken months before. We do this and then no one reads it.
Honest question, did you guys read it yourselves before asking the rest of the team to read it?
rocmcd
4 hours ago
If you didn't have the time to write something, why would you expect someone to spend the time to read it? Did _you_ read all of the documentation you generated?
jasongi
3 hours ago
Nobody willingly reads docs. Docs don't exist for the reader, they exist for the writer(s) - because it saves them having to explain the same thing over and over again. Having docs is nice for continuity and for the people who take initiative to seek them out instead of just asking others, but their real value is turning daily (or hourly) 30 minute explanation into a link and a "let me know if you have any questions". The doc pays for itself the second time someone asks you about 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.
delfinom
4 hours ago
To be fair, AI writing is often unhuman. The biggest problem its more verbose than human writing. It adds additional not needed mental load in processing text.
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.
bcrosby95
4 hours ago
The AI seems to put it's internal reasoning into comments. I have to keep telling it to knock it the fuck off.
datakan
4 hours ago
You make a good point but it's also subjective. The documentation we need is all technical in nature so we aren't looking for Shakespeare or Tolkien here. We just need it to be accurate and usable, which it is.
nemomarx
4 hours ago
Part of being quickly usable might be the brevity or utilitarian style. Maybe it looks intimidatingly long?
yomismoaqui
4 hours ago
If that documentation serves another human-operated querying AI it already provides value as a cached work that prevents another AI from re-extracting that knowledge from the code (burning time & tokens in the process).
Another question is keeping those docs up to date...
xnx
3 hours ago
AI might be exposing the valuelessness of corporate busywork.
yoyohello13
4 hours ago
AI or not, most people never cared about documentation. I have always had to fight tooth and nail to get people to write shit down, and that hasn't changed with AI.
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.
phoghed
4 hours ago
Work for a big enough enterprise and you’ll spend tons of time making reams of documentation that nobody ever reads and only exists to check a box. Stick around long enough and maybe a 3rd party auditor will read some of it.
dfxm12
4 hours ago
In the context of documentation, it's not about disillusionment. It doesn't matter if you write it, an AI writes it, if there's a searchable wiki, a chat bot front end etc., your colleagues will track you down and ask you about it personally. They don't want documentation. They want to make their problem into your problem.
lardosaurusrex
4 hours ago
my issue is that people insist their written ai work -- including documentation -- is correct only for myself and many others to repeatedly discover this isn't the case.
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.
Imustaskforhelp
3 hours ago
others have commented some good comments on the documentation aspect. I wish to talk more about incentives instead. I will set aside the discussion of if the AI writing docs and people caring about AI written docs.
> 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)
lezojeda
4 hours ago
[dead]
happypappy123
4 hours ago
[dead]
ai_fry_ur_brain
4 hours ago
[dead]