8 ms·

You’re not familiar with Zig’s culture, I guess. Complain about the lack of documentation and be prepared for the flood of “just read the stdlib code” helpful c

by brabel 1y ago

You’re not familiar with Zig’s culture, I guess. Complain about the lack of documentation and be prepared for the flood of “just read the stdlib code” helpful comments by pretty much everyone who writes Zig right now. Because most APIs are just as hard to use as in this post (check things like HTTP and even basic file system operations) only the strongest survive.

hardwaresofton 1y ago
Yeah, thinking about this attitude positively, maybe it’s a feature — if only hard core people can comfortably figure it out, you get higher quality contributions? Not trying to imply that’s an explicit goal (probably instead just a resource problem), but an observation
- ksec 1y ago
  I think it is a trade off for between zig's development speed and documentation. It is Pre 1.0, extreme beta mode with lots of breaking changes. Generally speaking I think it is the right trade off for now. Purely inferring from Andrew and the Zig's team online character as I don't know them in person, I think they do care a lot of DX, things like compiling speed and tools. So I think once 1.0 come I won't be surprised if it will have extremely good documentation as well. And I would argue, writing good, simple, clear, detailed documentation is actually harder than writing code itself.
  - LambdaComplex 1y ago
    My quick skim of Wikipedia may not be telling the complete story, but it says the initial release was 9 years ago (February 2016). After nearly a decade, I would hope that things would be out of "extreme beta mode," but I guess this isn't the case?
    - ksec 1y ago
      For most of its time it is simply a single person and part time project. Even to this day the team is nowhere near Rust or Go's resources.
      - LambdaComplex 1y ago
        Huh, I actually expected there to be a bigger team working on it. In that case: I'm really impressed.
      - tialaramex 1y ago
        In 2016, nine years ago, Andrew announced he'd been working on the new language "Zig" for a couple of months. In 2018, seven years ago, Andrew announced he'd go full-time on Zig and quit his paying job to live off donations instead. In 2020, so five years ago, Zig's 501(c)3 the ZSF was announced, to create a formal structure to hire more people in addition to the few already on Zig. So, "most of its time" is just not true. For "most of its time" Zig was a small, largely independently funded project for multiple people, for a tiny period it was a part-time project, and for a while after that it was solo, but those weren't the majority of its existence.
        throwawaymaths 1y ago
        yeah but i think you can count on one hand how many full time zig developers are paid by the foundation.
    - HumanOstrich 1y ago
      What's the benchmark for how long something can be pre-1.0? Seems like a nonsense argument.
      - yxhuvud 1y ago
        Something can be pre-1.0 as long as there are no stability guarantees.
      - pharrington 1y ago
        There is no benchmark. As a species, we don't even know know what a good programming language is, let alone how to reliably develop one. This stuff takes time, and we're all learning it together. I like to compare this to real world cathedral building. There are some cathedrals that are literally taking centuries to build! It's OK if the important, but difficult thing takes a long time to build.
        Dylan16807 1y ago
        Cathedrals are the opposite of extreme beta mode with lots of breaking changes.
        pharrington 1y ago
        Yes. I guess what I meant is that cathedrals are a complex system that we know how to do, and still they take ages to build properly.
      - Dylan16807 1y ago
        It's the combination of pre-1.0 and having rapid development speed that is being questioned here. And it's a good question, not nonsense. If you keep up the development pace you're going to approach stability. Unless you're in a manic spiral of rewrites.
      - throwawaymaths 1y ago
        https://github.com/ziglang/zig/milestone/2 https://github.com/ziglang/zig/milestone/2
    - littlestymaar 1y ago
      Same as Rust being almost a decade old when the first 1.0 was published. Making a programming language from scratch is a long endeavor when it's a one man project.
  - brabel 1y ago
    I've written many APIs. Never have I got it right without first writing lots of tests, finding the rough corners, improving it... and so on. Writing documentation after that is absolutely mandatory for the end result to be a high quality API. As you write how it is meant to work, you will definitely find things that don't really make sense, or that should not be as hard ( I think this post shows just such an API that hasn't gone through this process ). IMHO documentation is NOT optional. The implementation is NOT how you mean for the API to be used.
  - sshine 1y ago
    Unstable APIs are a good example of something that's extremely valuable early on. They unarguably cause confusion for everyone as they change. But it lets you choose the right abstractions that are going to stick for decades. If you're going to make a python2 -> python3 transition in your language, make sure it's X0 -> X1.
  - hardwaresofton 1y ago
    On the one hand, I totally get that pre 1.0 is the wild west (somewhat) and should be. The team is right in jealously guarding their ability to make changes. That said, others have pointed out that writing documentation and tests helps improve quality quite a bit, and in this case it would also increase usability. I think I'd agree with this stance, but there is no way I could make the statement that even most of the code I've written for public consumption had excellent documentation or examples. So I've got no leg to stand on there, just the armchair. > And I would argue, writing good, simple, clear, detailed documentation is actually harder than writing code itself. All the more reason why it must be done! A little silly but from my armchair maybe it's one of those "start with the interface you want and work backwards", but the problem is that approach can be at odds with mechanical sympathy and we know which side Zig lands on (and arguably should land on based on it's values).
- chrisandchris 1y ago
  Contributions to the Zig language or contributions to software using Zig (the latter is the one the post is about as I understand)? If so, I believe Zig will stay within a niche. Lower entry barriers allow "script kiddies" to easily start withe language, and they eventually will become leading engineers. Only a few people tend to go straight for the highest practice without "playing around". IMHO the reason, why PHP got so popular (it was not good back then, just very very easy to start with).
  - hardwaresofton 1y ago
    > Contributions to the Zig language or contributions to software using Zig (the latter is the one the post is about as I understand)? Yes. I think a contributor that really wanted to help the ecosystem would start in the stdlib and then start moving outwards. Even if it was LLM-assisted, I think it could be high value. IIRC Loris already has an engine for building websites with Zig, but making sure that every Zig library has docs (similar to rustdocs) might be a great start. It is incredibly useful to have a resource like rustdocs, both the tooling and the web sites that are easily browsable. Again, maybe everyone in the Zig ecosystem just has amazing editor setups and massive brains, but I personally really like the ease of browsing rustdoc. > If so, I believe Zig will stay within a niche. Lower entry barriers allow "script kiddies" to easily start withe language, and they eventually will become leading engineers. Only a few people tend to go straight for the highest practice without "playing around". IMHO the reason, why PHP got so popular (it was not good back then, just very very easy to start with). I agree, but I'd add that the niche they're aiming for is systems programming, so they're probably fine :). The average hacker there is expecting C/C++ or to be near the metal, and I think Zig is a great fit there. They're likely not going to convince people who write Ruby, but it feels reasonable for C hackers. Also I want to just be clear that I think Zig has a lot of motivating factors! They're doing amazing things like zig cc, unbelievably easy, "can't believe it's not butter" cross-compilation, their new explicit/managed I/O mechanism, explicit allocators as a default, comptime, better type ergonomics. It's a pretty impressive language.
    - flohofwoe 1y ago
      > already has an engine for building websites with Zig, but making sure that every Zig library has docs Tbh, this sort of auto-generated docs from source code is not all that useful, since you get that same information right in the IDE via the language server. The important documentation part that's currently missing is how everything is supposed to work together in the stdlib, not the 'micro-documentation' of what a single type or function does. And for this sort of information it's currently indeed better to look at example code (e.g. the stdlib's testing code). IMHO it's way too early for this type of high-level documentation, since things change all the time in the stdlib. Putting much work into documenting concepts that are discarded again anyway doesn't make much sense.
- rjh29 1y ago
  I think it is intentional. They don't want to attract low-commitment beginners while the language is heavily changing (and explicitly in beta). Such people will ask questions and ask for documentation but contribute nothing.
- DannyBee 1y ago
  More likely you get people who have the same groupthink, which has both ups and downs. Their contribution quality is probably not that well correlated.
virtualritz 1y ago
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.
keyle 1y ago
That would hurt adoption. I understand things move fast but if you want people to make the switch other than hello world, it has to be at a minimum cosy. Sending them to hell and find your way out isn't a good move long term. I tried Zig a couple of times and I got that feeling: very powerful and clever language but not really for me, I don't have the headspace, sorry. I need something I can debug after an 8 hours dayjob, a commute and having put the kids to bed. It better be inviting & fun! (Hi, C).
- throwawaymaths 1y ago
  after chasing some insane macro gymnastics whivh are there to make the c portble, i came to understand that zig is more easy to debug than c
  - keyle 1y ago
    I don't live in that universe! I thanos flicked it off!
- skupig 1y ago
  Yeah, I had the same experience. I had an embedded project where I would need to use C libraries, and it seemed like a great excuse to try Zig, but it spat out a ton of esoteric errors I couldn't be bothered to figure out and I went back to Nim.
littlestymaar 1y ago
The key problem with Zig nowadays is how much of its community and adoption is driven by anti-Rust sentiment. As a result, while Rust puts beginner onboarding and documentation at the center of its culture, as opposed to the “C neckbeard”'s culture, Zig is going the other way around. (Loris Cro being a key community figure isn't helping in any way, and it's a good remainder that if you don't clear up your community from bullies from the beginning, they will turn your entire community to a miserable place. And that's a shame because from what I've seen, Andrew Kelley seems to be a very cool guy in addition to being very smart).
- bnolsen 1y ago
  The anti rust sentiment in large part is dissatisfaction with rust itself. Ziglang.org lists 3 principles of zig: no hidden control flow, no hidden memory allocations, no macros. This is not anti rust for the sake of being anti rust, this is anti lots of popular languages, and I personally like it.
  - littlestymaar 1y ago
    That isn't “anti Rust” at all, it's just a different set of trade offs, and it's fine that it attracts developers who don't like the set of trade offs Rust make. What's not very good are the people who don't like Rust, who are uneasy with Rust is eating the system programming world, and are now pushing Zig as the champion of the resistance about Rust. It happens a lot, unfortunately.
- pjmlp 1y ago
  Not only, the whole handmade movement puts me off. It is the anti-intelectualism from Go culture, gone wild against C++, Rust, Swift, anything modern, or even tools, using game engines versus doing the whole computer from scratch for a game.
  - kristoff_it 1y ago
    Zig is not really a handmade project, case in point both Andrew and I are blocked on social media by the two gods of the handmade movement (casey and john) and, according to their die hard fans, Andrew gave a talk at the last handmade conference that caused the community to split apart (the reality is a bit more complex than this, but Andrew's talk is certainly one that you wouldn't see at their new "better software" conference). Andrew's talk is here (second event after the two people chatting while sitting on chairs): https://handmadecities.com/media/seattle-2024/hms-day-one/ https://handmadecities.com/media/seattle-2024/hms-day-one/ Here you can see a particularly funny (but also sad) reaction by one of these people https://drive.proton.me/urls/MB1EB4EF34#YZdvmAvBFp1C https://drive.proton.me/urls/MB1EB4EF34#YZdvmAvBFp1C > using game engines versus doing the whole computer from scratch for a game That said you are doing yourself a disservice if you think that not using an engine to make a game is a form of "anti-intellectualism".
deleted 1y ago
[deleted]

by brabel 1y ago

hardwaresofton 1y ago

Yeah, thinking about this attitude positively, maybe it’s a feature — if only hard core people can comfortably figure it out, you get higher quality contributions? Not trying to imply that’s an explicit goal (probably instead just a resource problem), but an observation

ksec 1y ago
I think it is a trade off for between zig's development speed and documentation. It is Pre 1.0, extreme beta mode with lots of breaking changes. Generally speaking I think it is the right trade off for now. Purely inferring from Andrew and the Zig's team online character as I don't know them in person, I think they do care a lot of DX, things like compiling speed and tools. So I think once 1.0 come I won't be surprised if it will have extremely good documentation as well. And I would argue, writing good, simple, clear, detailed documentation is actually harder than writing code itself.
- LambdaComplex 1y ago
  My quick skim of Wikipedia may not be telling the complete story, but it says the initial release was 9 years ago (February 2016). After nearly a decade, I would hope that things would be out of "extreme beta mode," but I guess this isn't the case?
  - ksec 1y ago
    For most of its time it is simply a single person and part time project. Even to this day the team is nowhere near Rust or Go's resources.
    - LambdaComplex 1y ago
      Huh, I actually expected there to be a bigger team working on it. In that case: I'm really impressed.
    - tialaramex 1y ago
      In 2016, nine years ago, Andrew announced he'd been working on the new language "Zig" for a couple of months. In 2018, seven years ago, Andrew announced he'd go full-time on Zig and quit his paying job to live off donations instead. In 2020, so five years ago, Zig's 501(c)3 the ZSF was announced, to create a formal structure to hire more people in addition to the few already on Zig. So, "most of its time" is just not true. For "most of its time" Zig was a small, largely independently funded project for multiple people, for a tiny period it was a part-time project, and for a while after that it was solo, but those weren't the majority of its existence.
      - throwawaymaths 1y ago
        yeah but i think you can count on one hand how many full time zig developers are paid by the foundation.
  - HumanOstrich 1y ago
    What's the benchmark for how long something can be pre-1.0? Seems like a nonsense argument.
    - yxhuvud 1y ago
      Something can be pre-1.0 as long as there are no stability guarantees.
    - pharrington 1y ago
      There is no benchmark. As a species, we don't even know know what a good programming language is, let alone how to reliably develop one. This stuff takes time, and we're all learning it together. I like to compare this to real world cathedral building. There are some cathedrals that are literally taking centuries to build! It's OK if the important, but difficult thing takes a long time to build.
      - Dylan16807 1y ago
        Cathedrals are the opposite of extreme beta mode with lots of breaking changes.
        pharrington 1y ago
        Yes. I guess what I meant is that cathedrals are a complex system that we know how to do, and still they take ages to build properly.
    - Dylan16807 1y ago
      It's the combination of pre-1.0 and having rapid development speed that is being questioned here. And it's a good question, not nonsense. If you keep up the development pace you're going to approach stability. Unless you're in a manic spiral of rewrites.
    - throwawaymaths 1y ago
      https://github.com/ziglang/zig/milestone/2 https://github.com/ziglang/zig/milestone/2
  - littlestymaar 1y ago
    Same as Rust being almost a decade old when the first 1.0 was published. Making a programming language from scratch is a long endeavor when it's a one man project.
- brabel 1y ago
  I've written many APIs. Never have I got it right without first writing lots of tests, finding the rough corners, improving it... and so on. Writing documentation after that is absolutely mandatory for the end result to be a high quality API. As you write how it is meant to work, you will definitely find things that don't really make sense, or that should not be as hard ( I think this post shows just such an API that hasn't gone through this process ). IMHO documentation is NOT optional. The implementation is NOT how you mean for the API to be used.
- sshine 1y ago
  Unstable APIs are a good example of something that's extremely valuable early on. They unarguably cause confusion for everyone as they change. But it lets you choose the right abstractions that are going to stick for decades. If you're going to make a python2 -> python3 transition in your language, make sure it's X0 -> X1.
- hardwaresofton 1y ago
  On the one hand, I totally get that pre 1.0 is the wild west (somewhat) and should be. The team is right in jealously guarding their ability to make changes. That said, others have pointed out that writing documentation and tests helps improve quality quite a bit, and in this case it would also increase usability. I think I'd agree with this stance, but there is no way I could make the statement that even most of the code I've written for public consumption had excellent documentation or examples. So I've got no leg to stand on there, just the armchair. > And I would argue, writing good, simple, clear, detailed documentation is actually harder than writing code itself. All the more reason why it must be done! A little silly but from my armchair maybe it's one of those "start with the interface you want and work backwards", but the problem is that approach can be at odds with mechanical sympathy and we know which side Zig lands on (and arguably should land on based on it's values).
chrisandchris 1y ago
Contributions to the Zig language or contributions to software using Zig (the latter is the one the post is about as I understand)? If so, I believe Zig will stay within a niche. Lower entry barriers allow "script kiddies" to easily start withe language, and they eventually will become leading engineers. Only a few people tend to go straight for the highest practice without "playing around". IMHO the reason, why PHP got so popular (it was not good back then, just very very easy to start with).
- hardwaresofton 1y ago
  > Contributions to the Zig language or contributions to software using Zig (the latter is the one the post is about as I understand)? Yes. I think a contributor that really wanted to help the ecosystem would start in the stdlib and then start moving outwards. Even if it was LLM-assisted, I think it could be high value. IIRC Loris already has an engine for building websites with Zig, but making sure that every Zig library has docs (similar to rustdocs) might be a great start. It is incredibly useful to have a resource like rustdocs, both the tooling and the web sites that are easily browsable. Again, maybe everyone in the Zig ecosystem just has amazing editor setups and massive brains, but I personally really like the ease of browsing rustdoc. > If so, I believe Zig will stay within a niche. Lower entry barriers allow "script kiddies" to easily start withe language, and they eventually will become leading engineers. Only a few people tend to go straight for the highest practice without "playing around". IMHO the reason, why PHP got so popular (it was not good back then, just very very easy to start with). I agree, but I'd add that the niche they're aiming for is systems programming, so they're probably fine :). The average hacker there is expecting C/C++ or to be near the metal, and I think Zig is a great fit there. They're likely not going to convince people who write Ruby, but it feels reasonable for C hackers. Also I want to just be clear that I think Zig has a lot of motivating factors! They're doing amazing things like zig cc, unbelievably easy, "can't believe it's not butter" cross-compilation, their new explicit/managed I/O mechanism, explicit allocators as a default, comptime, better type ergonomics. It's a pretty impressive language.
  - flohofwoe 1y ago
    > already has an engine for building websites with Zig, but making sure that every Zig library has docs Tbh, this sort of auto-generated docs from source code is not all that useful, since you get that same information right in the IDE via the language server. The important documentation part that's currently missing is how everything is supposed to work together in the stdlib, not the 'micro-documentation' of what a single type or function does. And for this sort of information it's currently indeed better to look at example code (e.g. the stdlib's testing code). IMHO it's way too early for this type of high-level documentation, since things change all the time in the stdlib. Putting much work into documenting concepts that are discarded again anyway doesn't make much sense.
rjh29 1y ago
I think it is intentional. They don't want to attract low-commitment beginners while the language is heavily changing (and explicitly in beta). Such people will ask questions and ask for documentation but contribute nothing.
DannyBee 1y ago
More likely you get people who have the same groupthink, which has both ups and downs. Their contribution quality is probably not that well correlated.

virtualritz 1y ago

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.

keyle 1y ago

That would hurt adoption. I understand things move fast but if you want people to make the switch other than hello world, it has to be at a minimum cosy. Sending them to hell and find your way out isn't a good move long term. I tried Zig a couple of times and I got that feeling: very powerful and clever language but not really for me, I don't have the headspace, sorry. I need something I can debug after an 8 hours dayjob, a commute and having put the kids to bed. It better be inviting & fun! (Hi, C).

throwawaymaths 1y ago
after chasing some insane macro gymnastics whivh are there to make the c portble, i came to understand that zig is more easy to debug than c
- keyle 1y ago
  I don't live in that universe! I thanos flicked it off!
skupig 1y ago
Yeah, I had the same experience. I had an embedded project where I would need to use C libraries, and it seemed like a great excuse to try Zig, but it spat out a ton of esoteric errors I couldn't be bothered to figure out and I went back to Nim.

littlestymaar 1y ago

The key problem with Zig nowadays is how much of its community and adoption is driven by anti-Rust sentiment. As a result, while Rust puts beginner onboarding and documentation at the center of its culture, as opposed to the “C neckbeard”'s culture, Zig is going the other way around. (Loris Cro being a key community figure isn't helping in any way, and it's a good remainder that if you don't clear up your community from bullies from the beginning, they will turn your entire community to a miserable place. And that's a shame because from what I've seen, Andrew Kelley seems to be a very cool guy in addition to being very smart).

bnolsen 1y ago
The anti rust sentiment in large part is dissatisfaction with rust itself. Ziglang.org lists 3 principles of zig: no hidden control flow, no hidden memory allocations, no macros. This is not anti rust for the sake of being anti rust, this is anti lots of popular languages, and I personally like it.
- littlestymaar 1y ago
  That isn't “anti Rust” at all, it's just a different set of trade offs, and it's fine that it attracts developers who don't like the set of trade offs Rust make. What's not very good are the people who don't like Rust, who are uneasy with Rust is eating the system programming world, and are now pushing Zig as the champion of the resistance about Rust. It happens a lot, unfortunately.
pjmlp 1y ago
Not only, the whole handmade movement puts me off. It is the anti-intelectualism from Go culture, gone wild against C++, Rust, Swift, anything modern, or even tools, using game engines versus doing the whole computer from scratch for a game.
- kristoff_it 1y ago
  Zig is not really a handmade project, case in point both Andrew and I are blocked on social media by the two gods of the handmade movement (casey and john) and, according to their die hard fans, Andrew gave a talk at the last handmade conference that caused the community to split apart (the reality is a bit more complex than this, but Andrew's talk is certainly one that you wouldn't see at their new "better software" conference). Andrew's talk is here (second event after the two people chatting while sitting on chairs): https://handmadecities.com/media/seattle-2024/hms-day-one/ https://handmadecities.com/media/seattle-2024/hms-day-one/ Here you can see a particularly funny (but also sad) reaction by one of these people https://drive.proton.me/urls/MB1EB4EF34#YZdvmAvBFp1C https://drive.proton.me/urls/MB1EB4EF34#YZdvmAvBFp1C > using game engines versus doing the whole computer from scratch for a game That said you are doing yourself a disservice if you think that not using an engine to make a game is a form of "anti-intellectualism".

deleted 1y ago

[deleted]