Comment by virtualritz

Ai is great at block comments, there is no excuse. Add to that a small anotated usage example written by a human and this whole post would have not existed.

Lack of docs also cripple AI from understanding, so future adoption becomes even more bleak.

If an api or library developer didnt bother doing even bare minimum docs, my confidence in the library drops aswell.

Did they skip testing aswell? Ran the happy path for a day and called it good?

This post sour my interest in zig. Its now obvious to me now why rust took much of its market.

As a senior dev I’m also passionate about docs and communication, and actually kind of love the process of agonizing over a bunch of rST files to get the perfect manual that’s both an on-boarding guide and also a reference of all the nooks and crannies.

I think what I’ve come to realize is that when I feel a barrier toward doing that work, it’s a sign that I don’t actually like the underlying API. I don’t want to document it or craft examples or tutorials because in my mind the API sucks, it’s transitional, and documenting it in its current state is going to somehow lock in a bad interface and further increase the effort required to change and fix it up later.

It's just not reasonable to expect volunteers to write eloquent documentation when it's likely it will just get flushed

At the same time, if you want to use Claude to read the source and narrate how it works to you that’s trivial to do as a user.

I don't want to read ai slop comments. If you cant be bothered writing docs, I cant be bothered learning to use your library.