HN Reader

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

As soon as some widget in the corner of a site wiggles to get my attention, I leave. If you/they want people to actually read their articles they shouldn't try to distract readers as soon as they start.

Don't fall into the trap of the new SEO for AIs. LLM are just like users. https://passo.uno/writing-for-llms-ai-chatbots/

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.

AI will make it easy to get your documentation up for your users!

> Step one, write the documentation yourself.

> Step two, bots hit your website hundreds of times per minute.

> Step three, users never come to your site, they use OpenAI's site.

> Step four, ??? openAI profits

An effect I've found of building agents that interacts with an API is that the bot serves as a smoke test for error handling. If your API doesn't return a clear and actionable error, or doesn't validate json fields clearly or correctly, the bot will end up finding it out and getting confused.

I can imagine a near future where crud endpoints are just entirely tested by an AI service that tries to read the docs and navigate the endpoints and picks up any inconsistencies and faults.

Assuming the app in question is open source, which certainly not all of them are, why would the AI read the docs, if it can read the source?

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

Good docs don’t fix bad apps or APIs though. I get the sense that demand for docs is a signal that there’s a deeper problem with DX. Good docs generally only exist in places where they’ve given the rest of the DX enough love in the first place, so it’s more of a mark of quality than a means to quality.

How do you turn off dark mode on that site? Hurts my eyes

> This guide provides best practices for creating documentation that works effectively for both human readers and AI/LLM consumption in RAG systems.

What I'd be interested in seeing is best practices for creating documentation intended only for consumption by RAG systems, with the assumption that it's much easier and cheaper to do (and corresponding best practices for prompting systems to generate optimal output for different scenarios).

A bit off topic, but I've been finding myself write "plan.txt" files for claude code.

1. Write plan 2. Ask Claude to review for understandability 3. Update as needed until it's clear 4. Execute the task(s) in the plan.

I'm finding Claude gets much further on the first pass. And I can version the plans.

Excellent advice. Good documentation makes a huge difference in AI-assisted software development.

Makes web scraping easier too.

I need to register kap.ai if it isn't already (Ka pai being Māori for "Well done!").