[HN Gopher] Writing documentation for AI: best practices
___________________________________________________________________
Writing documentation for AI: best practices
Author : mooreds
Score : 119 points
Date : 2025-06-18 16:23 UTC (6 hours ago)
(HTM) web link (docs.kapa.ai)
(TXT) w3m dump (docs.kapa.ai)
| emil_sorensen wrote:
| 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).
| esafak wrote:
| Now people just have a better incentive :)
| mooreds wrote:
| "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
| nlawalker wrote:
| Honest question - what do you mean? What's the better
| incentive?
| esafak wrote:
| The documentation is now not just for other people, but for
| your own productivity. If it weren't for the LLM, you might
| not bother because it's in your memory. But the LLM does
| not have access to that yet :)
| jilles wrote:
| 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....
| corysama wrote:
| 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
| arscan wrote:
| In other words, people are discovering the value of standard
| software engineering practices. Which, I think is a good
| thing.
| bobbiechen wrote:
| Related: "If an AI agent can't figure out how your API works,
| neither can your users" (from my employer's blog)
|
| https://stytch.com/blog/if-an-ai-agent-cant-figure-out-how-y...
| thom wrote:
| Yeah, I've started to think AI smoke tests for cognitive
| complexity should be a fundamental part of API/schema design
| now. Even if you think the LLMs are dumb, Stupidity as a
| Service is genuinely useful.
| QRY wrote:
| 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!
| shafyy wrote:
| It's the same for SEO also. Good structure, correct use of HTML
| elements, quick loading, good accessibility, etc. Sure, there
| are "tricks" to improve your SEO, but the general principles
| are also good if you were not doing SEO.
| drusepth wrote:
| This is also the hilarious part of "prompt engineering".
|
| It's just effective linguistics and speech; what people have
| called "soft skills" forever is now, obviously, trying to be a
| science for some reason.
| ketzo wrote:
| A really effective prompt is created by developing an
| accurate "mental model" of the model, understanding what
| tools it does and doesn't have access to, what gives it
| effective direction and what leads it astray
|
| Otherwise known as empathy
| basisword wrote:
| 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 wrote:
| 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.
| MK_Dev wrote:
| How do you turn off dark mode on that site? Hurts my eyes
| emil_sorensen wrote:
| Thanks for the feedback. We should definitely add that. :)
| retsibsi wrote:
| In Firefox, Reader View (F9) seems to handle it well.
| croes wrote:
| 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 wrote:
| AI doesn't adapt to anything. Training creates a fixed model
| that doesn't change until you replace it.
| theletterf wrote:
| 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/
| steveklabnik wrote:
| Most of the things described in this document are also good for
| humans. The justification is different, but the result is the
| same.
| pixl97 wrote:
| 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.
| AvAn12 wrote:
| Makes web scraping easier too.
| intellectronica wrote:
| Excellent advice. Good documentation makes a huge difference in
| AI-assisted software development.
| remram wrote:
| 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
| nlarew wrote:
| If your software business relies on people coming to your site
| to read docs then you were cooked from the start. It's about
| enabling your users whether they're on your site, ChatGPT, or
| anywhere else.
| namuol wrote:
| 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.
| wiremine wrote:
| 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.
| andy99 wrote:
| 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.
| reaperducer wrote:
| _As soon as some widget in the corner of a site wiggles to get
| my attention, I leave._
|
| Here's a bookmarklet I found on HN years and years ago. I have
| it bound to a hot key so whenever a web site does something
| stupid like that, I can dismiss it with a keystroke.
|
| Works about 90% of the time, and doesn't require any
| installation of anything.
|
| javascript:(function()%7B(function%20()%20%7Bvar%20i%2C%20eleme
| nts%20%3D%20document.querySelectorAll('body%20*')%3Bfor%20(i%20
| %3D%200%3B%20i%20%3C%20elements.length%3B%20i%2B%2B)%20%7Bif%20
| (getComputedStyle(elements%5Bi%5D).position%20%3D%3D%3D%20'fixe
| d')%20%7Belements%5Bi%5D.parentNode.removeChild(elements%5Bi%5D
| )%3B%7D%7D%7D)()%7D)()
| andy99 wrote:
| Thanks! I do have ublock origin and can typically get rid of
| these if I need to. It's just the frustration of going to
| websites that ostensibly want me to read something that see
| fit to destroy my focus as soon as I try to start.
___________________________________________________________________
(page generated 2025-06-18 23:00 UTC)