Most of the things described in this document are also good for humans. The justification is different, but the result is the same.
pixl97 · 20m ago
Or as I like to say, if current AI cannot explain your documentation well, then it's very likely humans can't either, your documentation sucks.
emil_sorensen · 3h ago
OP here. It's kind of ironic that making the docs AI-friendly essentially just ends up being what good documentation is in the first place (explicit context and hierarchy, self-contained sections, precise error messages).
jilles · 2h ago
It's similar for writing code. Suddenly people are articulating their problems to the LLM and breaking it down in smaller sub-problems to solve....
arscan · 1h ago
In other words, people are discovering the value of standard software engineering practices. Which, I think is a good thing.
corysama · 2h ago
It has changed how I structure my code. Out of laziness, if I can write the code in such a way that each step follows naturally from what came before, "the code just writes itself!" Except now it's literally true :D
QRY · 1h ago
Thank you for sharing this, it's really helpful to have this as top-down learning resource.
I'm in the process of learning how to work with AI, and I've been homebrewing something similar with local semantic search for technical content (embedding models via Ollama, ChromaDB for indexing). I'm currently stuck at the step of making unstructured knowledge queryable, so these docs will come in handy for sure. Thanks again!
bobbiechen · 1h ago
Related: "If an AI agent can't figure out how your API works, neither can your users" (from my employer's blog)
Honest question - what do you mean? What's the better incentive?
mooreds · 3h ago
"GEO[0] has entered the chat."
We see a surprising number of folks who discover our product from GenAI solutions (self-reported). I'm not aware of any great tools that help you dissect this, but I'm sure someone is working on them.
0: Generative Engine Optimization
MK_Dev · 2h ago
How do you turn off dark mode on that site? Hurts my eyes
retsibsi · 1h ago
In Firefox, Reader View (F9) seems to handle it well.
emil_sorensen · 2h ago
Thanks for the feedback. We should definitely add that. :)
AvAn12 · 39m ago
Makes web scraping easier too.
basisword · 3h ago
I wish companies would invest more in docs. It's too hard to keep the quality high if it's just another thing for engineers to do. I've seen too many cases where a small group invests lots of time and effort bringing the docs up to standard and then another person or group comes along and starts dragging down the quality because they can't be bothered taking to time to see how and where their information fits and ensuring the formatting and styles are maintained.
Eventually the quality drops to such a level that some poor bastard spends their time bringing it all back up to standard - and the cycle repeats.
simonw · 42m ago
The most important characteristic of any internal documentation is trust. People need to trust it. If they trust it, they'll both read it and contribute to it. If they don't trust it they'll ignore it and leave it to rot.
Gaining that trust is really hard. The documentation needs to be safe to read, in that it won't mislead you and feed you stale information - the moment that happens, people lose trust in it.
Because the standard of internal docs at most companies is so low, employees will default to not trusting it. They have to be won over! That takes a lot of dedicated work, both in getting the documentation to a useful state and promoting it so people give it a chance.
croes · 2h ago
I thought one of the use cases of AI is to write documentation?
And I thought AI adapts to humans, now it seems the other way around
svachalek · 2h ago
AI doesn't adapt to anything. Training creates a fixed model that doesn't change until you replace it.
I'm in the process of learning how to work with AI, and I've been homebrewing something similar with local semantic search for technical content (embedding models via Ollama, ChromaDB for indexing). I'm currently stuck at the step of making unstructured knowledge queryable, so these docs will come in handy for sure. Thanks again!
https://stytch.com/blog/if-an-ai-agent-cant-figure-out-how-y...
We see a surprising number of folks who discover our product from GenAI solutions (self-reported). I'm not aware of any great tools that help you dissect this, but I'm sure someone is working on them.
0: Generative Engine Optimization
Eventually the quality drops to such a level that some poor bastard spends their time bringing it all back up to standard - and the cycle repeats.
Gaining that trust is really hard. The documentation needs to be safe to read, in that it won't mislead you and feed you stale information - the moment that happens, people lose trust in it.
Because the standard of internal docs at most companies is so low, employees will default to not trusting it. They have to be won over! That takes a lot of dedicated work, both in getting the documentation to a useful state and promoting it so people give it a chance.