Hang on, that sounds like common corporate SaaS apps.
It's kind of fascinating that we never were willing to do these things for humans but now that AI needs it ... we are all in. A bit depressing in the sense that I think mostly the reason we happy to do it for AI is that we perceive it will benefit us personally rather than some abstract future human.
In fact, the only area I've been struggling with are "Concepts" because they have less clear boundaries for the right amount of detail.
Here is what I've been working on: https://github.com/super-productivity/super-productivity/wik...
In my case right now, our users are civil engineers, they just want to be able to use our software to model the environment. They really don't want to become an expert programmer on top of that.
They just want to be able to build their thing, like a bridge, so they can make money, and plug numbers into our software to do that.
It's like making a hammer, the documentation needed for forging a hammer out of steel will be radically different from using the hammer to build a house or doing ortho surgery.
I guess that just never occurred to anybody before.
Somebody pointed out that those Markdown files might be helpful for people to read directly. Bit of an Emperor's new clothes moment. (I wanted to slap a : rolling_on_the_floor_laughing: reaction on it, but sadly it turns out I'm actually too chickenshit to do that in today's job market.)
That's the main reason I hesitate to ever call it AI. They are ML for sure, but I don't see how intelligence fits into LLMs.
One of the best parts of LLMs is that you can use them to bootstrap your documentation, or scan for outdated things, etc, far more quickly than ever before.
Don't just throw a mountain at it and ask it to get it right, but use a targeted process to identify inconsistencies, duplicates, etc, and then resolve those.
And then you have better onboarding material for the next human OR llm...
No, that's forward. Any documentation an AI can make, another AI can regenerate. If an LLM didn't write the code, it shouldn't document it either. You don't want to bake in slop to throw off the next LLM (or person).
My experience is that most people fail to capture this ultra-valuable documentation, but AI never does.
Then books gave way to the web and there was no longer a publishing deadline or copy editor and we just kinda stopped caring. The users still cared, but many producers stopped.
We had an art and we gave it up. Not completely, but substantially.
> It's kind of fascinating that we never were willing to do these things for humans but now that AI needs it ... we are all in. A bit depressing in the sense that I think mostly the reason we happy to do it for AI is that we perceive it will benefit us personally rather than some abstract future human.
I don't think that's the reason.
I think it's because they take time, and few people were willing to put in time for "maybe it'll make writing the actual code faster" gains when the code was going to take a few times longer to write itself.
You also can get faster feedback to iterate on your spec now, which improves the probability of it helping future-you.
So combine that with the fact that the llms are more likely to get lost if you don't spec stuff in advance, and the value of up-front work is higher (whereas a human is more likely to land on the right track, just more slowly than otherwise, making the value harder to quantify).
Actually there's a lot of projection there too; I don't read documentation in detail. And nowadays, I point an LLM at documentation so that it can find the details I would otherwise skip over.
The destruction of the millennial attention span is real, and it's worse in the younger generations, lmao.
Imagine how crippled you would be if you felt compelled to follow every comment thread to its end.
We're just monkeys looking for the good bits among a pile of rotten fruit.
So you're arguing back and forth about exactly which fields should be collected where and meanwhile the world is changing around you. The person who insisted on an absolutely minimal signup page has changed jobs, the new hire prioritizes complete data even if it means more signup bounces.
Weeks and months are going by and there's nothing to click on and still nothing to tether the project to reality or limit the scope of debate. High functioning teams can avoid this, but they don't always control who inserts themselves into the conversation.
And of course as soon as coding starts the spec is out of date unless you absolutely nailed it which I've never seen happen in 15 years. Once a user sees the software and gives feedback it probably needs to be rewritten. Maintaining the spec (pre-LLM) was not that much less work than maintaining the software itself. All this time the world around the software is changing and the spec needs to be updated to reflect that.
And while the spec helps in understanding the system, ultimately you still need to understand the code and it.
But now the time between spec and working code is greatly reduced and spec updating can be automated to an extent. The cost is greatly reduced and the benefits have increased, so people like specs now.
Almost sounds like an Orielly book
Matthew B. Doar (2011). Practical JIRA Plugins. O’Reilly.
https://www.oreilly.com/library/view/practical-jira-plugins/...
In case anyone was wondering. Which they probably weren’t :p
[1] https://www.oreilly.com/animals.csp?x-search=duck&x-sort=old...
Generative AI wasn't a thing at the time, but I had to resort to a combination of OCR, simulated user input, and print capture to drive the application and export data.
Had the developers been aware of the Windows DRM APIs that block screen capture, or the fact that text is easily recoverable from PostScript files with minimal formatting, I don't know what I would have done.
The irony is that the process this replaced involved giving cheap offshore labor full read-only remote access to all data in the system, which was by any measure a far more serious security risk than otherwise authorized employees using tools running locally with no network access provided by established, trustworthy vendors to automate their work.
We built isagent.dev for exactly this reason, serve human content to humans, serve agent optimized content to agents.
If you want to take the stance that those designers (and people who don't want to consume plain text web) are wrong, sure I guess. But I prefer to take the stance that people and agents should receive content in their desired format.