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.

Which is true, in a way, the data put down as documentation can now be calculated in seconds, and documentation is just a cache.

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.

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.

Another question is keeping those docs up to date...

Honest question, did you guys read it yourselves before asking the rest of the team to read 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.

If you did check it for accuracy then I don't understand how you compressed months of work into minutes.

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.

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.

https://tombedor.dev/human-attention-and-human-effort/

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.

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.

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.

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.

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

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.

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.

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.

I mean, maybe your 3 month prediction is correct. But by definition that expert's 3 month prediction wasn't accurate because software engineering is still around and it's after April. We are 3.5 years in '6months until programming is solved'.

I've seen some people suggest that I should be require agents to produce an extremely detailed PR description and review that instead, which perhaps would have worked. But I don't understand the appeal. Why would I want to review a lossy, imprecise description of what the code does instead of reviewing the actual code and what it actually does?

I read the book how the internet happened (great book btw) and I would politely like to refuse this claim :)

Or perhaps there could be a separation between the computer and the internet (or more accurately the browsers)

When only computers existed, there were assists of working tools (maybe older versions of docs,excel etc.) but when the internet browsers happened (Netscape), from the very start of it, there were ideas of advertisement and monetization of it.

The only reason that internet turned out to be so open in the start was that Netscape wanted to have it open to get as much turf as possible before Microsoft realizes and they did everything and even then Microsoft had too much monopoly and they released Internet Explorer.

Before internet or pre-dawn of it, there were people with computer magazines and people tinkering and it might be one of you judging from writing code by hand :)

There was an real passion in it and people like you followed it, until the internet experiment really worked and then sooner or later things from internet started reverting to some form of enshittification and immense advertisements and stock markets wanting more advertisements leading to wanting more retention and wanting to create/replace life altogether (most literally Meta and its failed metaverse)

While writing this comment, I have come to insight: Internet had come to replace to the Television (Information Highway) but lately it has ended up becoming one. The last line of "That is until we forgot what it was for and made it replace life altogether." might apply to television as well and the only bottleneck during that time was the technology which seems to have been the internet as now we have youtube,insta,tiktok with infinite scroll feeds, so perhaps things have always been like this way but you were never exposed so much to that side but now its coming for the coding side of things which you are passionate about.

In that sense nothing is as good or as bad as it seems but we are certainly going on a downward trend perhaps depending on the metric and I would prefer living in the golden past so I envy you :)