[virtualritz]

I do not think this is a viable excuse any more.

I am just editing docs now that Claude Code writes for me. I am fanatic about developer docs (and I guess an exception as I love writing them) but with a set of concise instructions for CC and some writing style examples I get 90% there, sometimes 99%.

If you believe you don't have time for the last 1--10% you should not be in charge of writing any API used by anyone but yourself. Just my two c.

[aDyslecticCrow]

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.

[SoraNoTenshi]

There's also a fundamental difference in Zig and Rust. Ever tried reading std code in Rust? If you have, you would notice one thing really quick: it's borderline unreadable. It's a hornet's nest of Generics over constraint generics calling into indirections.

Of course, this isn't meant to be a defense for the lack of documentation on Zig's side, but in my experience, Zig's code definetly is much easier to read, just because for the fact, that Rust's std code is akin to C++'s stl.

One of the personal grimes i have with Zig is, that `anytype` makes the function contract kind of meaningless, because you can't see what is expected purely on the function definition.

[felixgallo]

Zig is just getting started and came way after rust.

[oblio]

I like Zig, but if we look at the numbers, the difference is probably more to do with funding that anything:

Zig (programming language) - First appeared 8 February 2016; 9 years ago

Rust (programming language) - First appeared January 19, 2012; 13 years ago

Also, Zig at this point isn't really a brand new language anymore. I have comments on their issues dating back to 2018, so it's been a very active language since at least then.

[jorams]

Those are not comparable dates. The Zig "first appeared" date is a few months into development by Andrew in his spare time. The Rust "first appeared" date is after 3 years of development by Graydon in his spare time, followed by 3 years of development by a Mozilla-sponsored team of engineers.

[aDyslecticCrow]

So they're gonna just finnish up their standard lib and THEN spend a year doing nothing but docs for everything they made?

Just getting started is an even bigger reason to have good docs to clearly communicate how the libraries and APIs work!

I wouldn't even read a push request containing a new function if the creator didn't bother writing a short description and usage clarification.

Getting started is a good excuse for limited libraries or support (same situationwith rust). But lack of even basic docs is not acceptable if you want user adoption.

[mikepurvis]

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.

[throwawaymaths]

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

[tel]

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.

[foxes]

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.

[BobbyJo]

Just because and AI produced it doesn't mean it is slop.

[ioasuncvinvaer]

But it is a pretty good signal of low quality.

[BobbyJo]

A signal is something you use to discern something in lue of direct information. In the case of docs, just look at them and if they suck, or are good, it doesn't really matter where they came from. That being said, Ill take AI generated docs over no docs, and no docs is very common.

[ioasuncvinvaer]

But how do you know if you can trust the docs if they are AI generated?

[BobbyJo]

How do you know if you can trust then if they are human generated? Your trust the people. AI isn't going to jump and just generate docs, a person has to prompt it, and you should expect the person to proof read and correct it. If the person turns out to be untrustworthy, you stop trusting them.

[pixl97]

I mean, the quality of docs before AI was pretty low quality and forums everywhere were filled with complaints about it, except in the case of a few exceptional pieces of software. If this is the case, just having docs at all seems to be a signal of low quality.

[ioasuncvinvaer]

No! Well written docs are a sign of quality. Obviously AI generated docs make me question whether they are actually correct which makes them useless.