6 ms·

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 e

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 1y ago
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.
- felixgallo 1y ago
  Zig is just getting started and came way after rust.
  - oblio 1y ago
    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 1y ago
      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.
      - deleted 1y ago
        [deleted]
      - deleted 1y ago
        [deleted]
  - aDyslecticCrow 1y ago
    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.
- deleted 1y ago
  [deleted]
- SoraNoTenshi 1y ago
  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.
foxes 1y ago
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 1y ago
  Just because and AI produced it doesn't mean it is slop.
  - ioasuncvinvaer 1y ago
    But it is a pretty good signal of low quality.
    - pixl97 1y ago
      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 1y ago
        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.
    - BobbyJo 1y ago
      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 1y ago
        But how do you know if you can trust the docs if they are AI generated?
throwawaymaths 1y ago
It's just not reasonable to expect volunteers to write eloquent documentation when it's likely it will just get flushed
tel 1y ago
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.
mikepurvis 1y ago
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.
deleted 1y ago
[deleted]

aDyslecticCrow 1y ago

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.

felixgallo 1y ago
Zig is just getting started and came way after rust.
- oblio 1y ago
  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 1y ago
    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.
    - deleted 1y ago
      [deleted]
    - deleted 1y ago
      [deleted]
- aDyslecticCrow 1y ago
  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.
deleted 1y ago
[deleted]
SoraNoTenshi 1y ago
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.

foxes 1y ago

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 1y ago
Just because and AI produced it doesn't mean it is slop.
- ioasuncvinvaer 1y ago
  But it is a pretty good signal of low quality.
  - pixl97 1y ago
    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 1y ago
      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.
  - BobbyJo 1y ago
    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 1y ago
      But how do you know if you can trust the docs if they are AI generated?

throwawaymaths 1y ago

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

tel 1y ago

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.

mikepurvis 1y ago

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.

deleted 1y ago

[deleted]