On: Microsoft rejects documentation PR because AI chat...

[apexalpha]

I'm not sure how I feel.

On the one hand I absolutely understand what all people are mad about. Docs are for humans, so LLMs understanding them shouldn't be a reason to reject something as simple as a table.

However, it also makes sense to make sure we not intentionally put things in a format that's bad for LLMs when other formats are available and just as useful for humans.

Personally, one of my favourite uses of ChatGPT is to just throw in any manpage followed by a question. If all manpages had specific sections that an LLM couldn't process I'd be a little annoyed at least.

I mean at that point why not take the (future) LLMs into acount?

[nunez → apexalpha]

Putting aside the insanity of rejecting a docs PR on the basis that "it's better for the AI," if their docs AI can't easily express tables yet, there should be a way of telling the user "Hey, this answer contains a table; go [here](https://path.to.docs) to look at it," just like audiobooks do.

[dijksterhuis → apexalpha]

to answer your question — YAGNI

i’ve seen plenty of questions like this over the years and they invariably lead to premature optimisation nightmare land.

build (or write the docs, in this case) for what’s needed today. what’s needed tomorrow is tomorrow dijksterhuis’ problem.

half the time i’ve been the one asking that question. so it’s not like i’ve been a saint in avoiding this trap.

[apexalpha → dijksterhuis]

>build (or write the docs, in this case) for what’s needed today. what’s needed tomorrow is tomorrow dijksterhuis’ problem.

But LLMs exist today...

[dijksterhuis → apexalpha]

but not everyone is relying solely on an LLM for documentation.

humans are still the primary audience for documentation.

if it ever gets to a point where no human is reading the docs, worry about it then (or close to no humans).

just because a new frontend framework gets released doesn’t mean we should all start switching to it today. it’s the same principle.