14 ms·
I'm not a Zig PM but the first obvious fix for the issues the OP wrote about is to write better documentation, including usage examples (the more the better, al
by hardwaresofton 1y ago
I'm not a Zig PM but the first obvious fix for the issues the OP wrote about is to write better documentation, including usage examples (the more the better, almost to a fault). Also doubles as a good time to reflect on whether the user is having to do too much.
If the tradeoff was absolute performance/avoiding introducing load-bearing performance-lowering abstraction I think that goal was achieved, but DX may have gone out the window.
- brabel 1y agoYou’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 agoYeah, 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 agoI 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 agoMy 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 agoFor 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 agoHuh, I actually expected there to be a bigger team working on it. In that case: I'm really impressed.
- tialaramex 1y agoIn 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 agoyeah but i think you can count on one hand how many full time zig developers are paid by the foundation.
- HumanOstrich 1y agoWhat's the benchmark for how long something can be pre-1.0? Seems like a nonsense argument.
- chrisandchris 1y agoContributions 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 agoI 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 agoMore 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 agoI 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 agoAi 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 agoZig is just getting started and came way after rust.
- oblio 1y agoI 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 agoThose 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 agoThat 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 agoafter 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 agoI don't live in that universe! I thanos flicked it off!
- skupig 1y agoYeah, 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 agoThe 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 agoThe 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 agoThat 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 agoNot 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 agoZig 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]
- ulbu 1y agoi find that zig is too oriented at doling out directives for what not to do instead of just collecting and teaching variants of how and what to do. the lack of documentation on this interface is a sore case in point.
- geon 1y agoYou can’t expect documentation this early. The new interface was just released.
- viraptor 1y agoIn serious codebases docs are not an afterthought. There's lots of places where you're expected to add both a new interface and docs together.
- 1y ago
- 0x696C6961 1y agoWriting good docs/examples takes a lot of effort. It would be a waste considering the amount of churn that happens in zig at this point.
- geon 1y agoYes. For now, that effort is better spent writing clear test cases that can serve to illustrate the intended usage. While tests aren’t quite as good documentation as actual documentation, they are guaranteed to not be out of date.
- dns_snek 1y agoThat's a false dichotomy, I'll take minimal bitrotten docs in a community wiki over no docs. There's no excuse not to at least have a stub that says "these features are evolving quickly but here are 10 open source projects that should serve as good references". Something - anything. As much as I like Zig, I dread returning to it after a few months of being out of the loop.
- 0x696C6961 1y agoIt's not a false dichotomy, it's a bandwidth issue. I'd rather the core team focus on stuff like incremental compilation.
- dns_snek 1y ago"No documentation" and "Core devs 'wasting' time on writing high quality documentation" aren't the only two options, that's what a false dichotomy means. Other options include but are not limited to providing minimal, low effort examples, high-level overview, linking to projects using these features, linking to relevant tests, commits, or source code, setting up an official community wiki and encouraging people to contribute.
- deleted 1y ago[deleted]
- 1y ago
- jakobnissen 1y agoThere is a cost to writing documentation - it takes time, which could be used to improve Zig in other areas. For code that is work-in-progress, it can make sense to not document until things are more settled. Of course documentation is good. But if you have to prioritize either a new feature, or a critical bugfix, or documentation, you often can't have it all
- wordofx 1y agoNa. It’s flat out laziness. Don’t make excuses. Either write docs or stop worrying code.
- hardwaresofton 1y agoThis is a good point, but one could make a point for the usefulness of documentation in “thinking like a user” which is a valuable exercise. I do very much prefer moving fast though, so I get it, docs-later is obviously a very valid way of doing things. If someone is excited about Zig and wanted to make a difference I guess it’s now obvious where they could have outsized impact!
- 7bit 1y agoDocs later is an okay approach, when you build something in a closed environment, where the only users know the code inside out. But when working in open-source and your goal is to have people adopt your software, then it's a bad point and a lazy excuse.
- HeartofCPU 1y agoVery good point
- aDyslecticCrow 1y agoThen they should not have relead the new api at all. Why release half finnished library.
- flohofwoe 1y ago
- pharrington 1y agoI'm not a Zig developer, but I imagine one reason why the Zig documentation is so spartan is because the language is still young and constantly evolving. It's really hard to devote the time and energy to writing documentation when you know that what you've written will just be wrong at some uncertain point in the future.
- baranul 1y agoMany would argue that Zig is not to be considered a young language anymore. It's been out for 9 plus years already. A different answer to that question, could be that its still unstable and making breaking changes (not 1.0), thus a reluctancy to focus on documentation to a level many consider satisfactory.