Writing documentation for AI: best practices

https://docs.kapa.ai/improving/writing-best-practices

107•mooreds•6h ago

Comments

emil_sorensen•5h 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).

esafak•5h ago

Now people just have a better incentive :)

mooreds•5h 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

nlawalker•2h ago

Honest question - what do you mean? What's the better incentive?

jilles•4h 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....

corysama•4h 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

arscan•3h ago

In other words, people are discovering the value of standard software engineering practices. Which, I think is a good thing.

bobbiechen•3h ago

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

QRY•3h 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!

shafyy•1h ago

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.

basisword•5h 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•2h 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.

MK_Dev•4h ago

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

emil_sorensen•4h ago

Thanks for the feedback. We should definitely add that. :)

retsibsi•3h ago

In Firefox, Reader View (F9) seems to handle it well.

croes•4h 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•4h ago

AI doesn't adapt to anything. Training creates a fixed model that doesn't change until you replace it.

theletterf•3h ago

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•2h ago

Most of the things described in this document are also good for humans. The justification is different, but the result is the same.

pixl97•2h 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.

AvAn12•2h ago

Makes web scraping easier too.

intellectronica•2h ago

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

remram•1h ago

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

namuol•1h ago

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•1h ago

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•1h ago

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•59m ago

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%20elements%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'fixed')%20%7Belements%5Bi%5D.parentNode.removeChild(elements%5Bi%5D)%3B%7D%7D%7D)()%7D)()

andy99•50m ago

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.

The unreasonable effectiveness of fuzzing for porting programs

Show HN: Workout.cool – Open-source fitness coaching platform

My iPhone 8 Refuses to Die: Now It's a Solar-Powered Vision OCR Server

Writing documentation for AI: best practices

Poline – An enigmatic color palette generator using polar coordinates

Show HN: I built a tensor library from scratch in C++/CUDA

Homomorphically Encrypting CRDTs

Game Hacking – Valve Anti-Cheat (VAC)

Terpstra Keyboard

Introduction to the A* Algorithm (2014)

MiniMax-M1 open-weight, large-scale hybrid-attention reasoning model

The Matrix (1999) Filming Locations – Shot-for-Shot – Sydney, Australia [video]

Is there a half-life for the success rates of AI agents?

Yes I Will Read Ulysses Yes

Revisiting Minsky's Society of Mind in 2025

Scrappy – Make little apps for you and your friends

Attimet (YC F24) – Quant Trading Research Lab – Is Hiring Founding Engineer

Framework Laptop 12 review

Locally hosting an internet-connected server

After millions of years, why are carnivorous plants still so small?

I counted all of the yurts in Mongolia using machine learning

PWM flicker: Invisible light that's harming our health?

A different take on S-expressions

The Grug Brained Developer (2022)

Should we design for iffy internet?

Show HN: Trieve CLI – Terminal-based LLM agent loop with search tool for PDFs

Real-time action chunking with large models

Building agents using streaming SQL queries

Spherical CNNs (2018)

Show HN: Free local security checks for AI coding in VSCode, Cursor and Windsurf

Writing documentation for AI: best practices

Comments

The unreasonable effectiveness of fuzzing for porting programs

Show HN: Workout.cool – Open-source fitness coaching platform

My iPhone 8 Refuses to Die: Now It's a Solar-Powered Vision OCR Server

Writing documentation for AI: best practices

Poline – An enigmatic color palette generator using polar coordinates

Show HN: I built a tensor library from scratch in C++/CUDA

Homomorphically Encrypting CRDTs

Game Hacking – Valve Anti-Cheat (VAC)

Terpstra Keyboard

Introduction to the A* Algorithm (2014)

MiniMax-M1 open-weight, large-scale hybrid-attention reasoning model

The Matrix (1999) Filming Locations – Shot-for-Shot – Sydney, Australia [video]

Is there a half-life for the success rates of AI agents?

Yes I Will Read Ulysses Yes

Revisiting Minsky's Society of Mind in 2025

Scrappy – Make little apps for you and your friends

Attimet (YC F24) – Quant Trading Research Lab – Is Hiring Founding Engineer

Framework Laptop 12 review

Locally hosting an internet-connected server

After millions of years, why are carnivorous plants still so small?

I counted all of the yurts in Mongolia using machine learning

PWM flicker: Invisible light that's harming our health?

A different take on S-expressions

The Grug Brained Developer (2022)

Should we design for iffy internet?

Show HN: Trieve CLI – Terminal-based LLM agent loop with search tool for PDFs

Real-time action chunking with large models

Building agents using streaming SQL queries

Spherical CNNs (2018)

Show HN: Free local security checks for AI coding in VSCode, Cursor and Windsurf