Ask HN: Is it time to start optimizing documentation for machines?

1 pointsdandrew51y ago2 comments

The more I lean into LLMs for my daily job, the less I find myself reading published documentation. A lot of time has historically been put into having really good, human-readable docs but I'm wondering if that will shift. If a service's documentation was written in a way optimized for training, what might it look like?

2 comments

JohnFen1y ago

> A lot of time has historically been put into having really good, human-readable docs but I'm wondering if that will shift.

I hope not. The state of documentation in general is already distressing. Making it even less aimed at people can only make it worse.

We shouldn't be worsening things in order to cater to LLMs. LLMs, if there is even a kernel of truth in all the hype, should be able to make good use of human-centered documentation.

dandrew5OP1y ago

True, good documentation is a rare thing. If the hype does hold and the current trajectory of things stays somewhat the same, I think it will be inevitable that the definition of "good documentation" will change. If it were geared towards a machine audience, I wonder if it would increase reliability and reduce hallucination.

I could imagine a hybrid approach as well where there are two versions: one for humans and one for machines. If respected, the crawlers could look for a special <meta> tag of sorts that points them to the machine version.

j / k navigate · click thread line to collapse