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.
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.
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.
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.
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.
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.
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).
(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).
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.
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/
Here you can see a particularly funny (but also sad) reaction by one of these people 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".
Depends on the attitude, not using an engine, because one wants to learn the whole stack, makes all sense, after all people need to learn how to make game engines, if nothing else for the next generation.
Not using one out of spite, because we do everything handmade over here attitude, is a completely different matter.
https://wiki.xxiivv.com/site/2025.html (the entry under 19b)
It seems this was a right vs. left (or liberal) split.
All this, combined with the fact that Zig, at best is still in beta quality and at worst amounts to a massive waste of everyone’s time, makes it unsurprising that people block you and simply refuse to engage with your loud community efforts, endless churn and crust tied to beta quality compiler.
> 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/
> Here you can see a particularly funny (but also sad) reaction by one of these people https://drive.proton.me/urls/MB1EB4EF34#YZdvmAvBFp1C
Regarding the links you posted:
In the first, at 2:30:40, Andrew Kelly publicly calls out a specific author of a competing technology in exaggerated, caricatured, and fabricated context.
In the second video, yet another author of a yet another competing technology directly points out this unapologetic and concerning behavior on Andrew Kelly’s part.
And now you—“VP of Community @ Zig Software Foundation”—assert your “righteous” stance by sharing these videos, while ironically pointing out that some of those same individuals (of competing technologies fame) block you on social media.
Too bad that doing your job probably means being as loud and visible online as possible to spread the molecules of Zig no matter what.
Maybe, or maybe the fact that Zig is a small independent project with limited resources has also something to do with it, and this kind of shaming says less about Zig than you'd think.
When I first joined the Zig project, Zig was still using the bootstrap compiler written in C++ that would not free memory (it took more than 4GB to compile the Zig compiler). Some people at the time were asking us to prioritize work on the package manager but Andrew rightfully wanted to prioritize rewriting the compiler instead. In hindsight this was the obviously right decision: a package manager implies that one can very easily add an order of magnitude more code to their project, stressing the performance of the compiler. If we had not prioritized core infrastructure over giving people what they wanted faster, today we would have people complaining that adding a single dependency to their project makes the build impossible to complete.
The Zig project has a huge scope and we are a small independent organization. This makes us extremely nimble and efficient, but it does mean that we need to do things in the order that makes the most sense for the project, not for what the public wants.
The fact that we develop in the open doesn't mean that the language is ready yet.
People that already have the required domain knowledge (and who have a tolerance for breaking changes) will have the opportunity to be early adopters if they wish to do so, others will have to wait for Zig to become more mature. And we do make this clear in releases and all forms of public communication.
We have gone a long way since the bootstrap compiler days, but we are still missing key infrastructure:
- we have a x86_64 custom backend but aarch64 is not complete yet - incremental compilation is showing that we can get instant rebuilds of large projects, but it has missing features and it doesn't work on all platforms yet - we need native fuzzing since AFL keeps regressing everytime a new version of LLVM comes out - for the longest time we haven't had a strong I/O story, now we're finally working on it
The time for paving the road for a new generation of programmers will come (it's in the ZSF mission statement btw), but first we need to finish the plumbing.
That sounds strange. Modern C++ requires very little manual memory management, at least when you're writing something high-level like a compiler. C++11 had been out for years when development on Zig started. Were they writing C++ old-school as C-with-classes and malloc() everywhere? Why not use a more appropriate language for the first prototype of a compiler for a brand new language?
Why would you care about these kinds of micro-optimizations at that stage of development, when you don't even know what exactly you need to build? We're not talking about serious algorithmic improvements like turning O(n²) into O(n) here.
> Freeing memory can actually cost you performance, so why not just let the OS clean up for you at exit(2)?
Because a compiler is not some simple CLI tool with a fixed upper bound on resource consumption.
it turns out that compiler speed is bound by a bunch of things, and it's death by a thousand cuts. If you have a slow compiler, and it takes forever to compile your compiler, your language becomes scelerotic, no one wants to make changes, and your language gets stuck in shitty choices.
> Because a compiler is not some simple CLI tool with a fixed upper bound on resource consumption
yes. thats right. a compiler is complex and should use several different allocation strategies for different parts. if your language steers you towards using malloc for everything then your compiler (assuming it's bootstrapped) will suffer, because sometimes there are better choices than malloc.
> When I first joined the Zig project, Zig was still using the bootstrap compiler written in C++ that would not free memory (it took more than 4GB to compile the Zig compiler). Some people at the time were asking us to prioritize work on the package manager but Andrew rightfully wanted to prioritize rewriting the compiler instead. In hindsight this was the obviously right decision: a package manager implies that one can very easily add an order of magnitude more code to their project, stressing the performance of the compiler. If we had not prioritized core infrastructure over giving people what they wanted faster, today we would have people complaining that adding a single dependency to their project makes the build impossible to complete.
I think you may have missed that the intention was always to rewrite the compiler to become self hosted. Improving the C++ implementation any more would've been pointless optimization.
Or, maybe it's this kind of redirection and evidence of a victim complex. Part of the reason that there's a patina of anti-Rust sentiment includes the dismissive attitude and swipes you, a the VP of Community at the Zig Software Foundation, take towards Rust and Rust developers by writing about topics you aren't involved in and don't have a solid grasp of.
https://kristoff.it/blog/raii-rust-linux/ https://lobste.rs/s/hxerht/raii_rust_linux_drama#c_gbn1q8
Or similarly, comments like this one in this thread: https://news.ycombinator.com/context?id=44994749
Loris is a bully, that's the problem, not his opinions.
* Sorry you feel that way, we try not to foster an inclusive environment that avoids language flamewars and negativity towards other languages
* Some specific examples of policies that are enacted in community spaces towards that end (e.g. some large programming language discord servers have specific rules against low effort language bashing content and memes)
* Take the opportunity to link back to positive things that the Zig team has said about Rust and places where folks have recommended it.
pcwalton infamously declared zig was "a massive step back for the industry" https://x.com/pcwalton/status/1568306598795431936?s=46&t=OCi.... He and the Rust Core Team had a big reputation for burning bridges. Even to this day, the new Rust leaders are happy to attack other memory safe languages like Go, declaring them "not memory safe" https://news.ycombinator.com/item?id=4467200
I think Kristoff remembers these attacks, and crucially how very few voices within the Rust community push back against Rust supremacism.
> [Golang] "not memory safe"
Both of these are entirely fair assessments, not "attacks". Golang really does have memory safety issues with concurrent code, and a memory-unsafe language like Zig is a step back even compared to Java/C#, let alone Rust.
The end result is that Rust's leaders either avoid interacting with other languages, or engage in flamewars. I think it's a big reason why Java, the most popular and successful memory safe language in the world, has little-to-no formal contacts with the Rust team.
I can't believe you really wrote that.
> Then [Anti Rust person] should have been perma-banned long ago [on an open forum]. Until this is done, we'll have to warn people about engaging with him…
You can hate kristoff, ignore him or attack his arguments. You can also love a piece of software and treat it as sacred. But other people should not be subjected to that love nor should they be canceled on account of it. Flag it or downvote. Beyond that, it's outside of our control.
I do agree though that kristoff should focus on Zig and not indulge in provoking old enemies. His valid points— deferring premature documentation for newbies until concepts are ironed out— are being lost in programming language holy wars.
I'm no language though…
> You can hate kristoff, ignore him or attack his arguments. You can also love a piece of software and treat it as sacred.
It's not about “love” or “being sacred” or even about Rust or Zig, it is about behaving in society. Most successful communities at some point meet toxic people who want to start holly wars and insult people. Successful communities are the one who ban those people, or at least coerce them into behaving through social pressure.
When you don't do that, you end up with bullies like Loris occupying prominent positions, and that's very bad for the community because it attracts people like that.
It has nothing to do with programming languages at all.
And sorry to say that bluntly, your discourse about “supremacism” “love” or “sacred” sounds very immature: programming languages are tools and engineering projects, not icons that should be worshipped or hated, they all have their strong points and warts (and god knows Rust has its share of annoyances…). Don't get dragged in holy wars by cult leaders like Loris.
Maybe you can make a hierarchy between technical criticism like this and the fact that Go isn't technically memory-safe[1], with Loris' abusive behavior of calling Rust maintainers names like “wankers”…
[1]: which is a criticism mostly coming from the Java crowd, by the way, not Rust, like the criticism of the simplistic garbage collection management in Go
What might be the better critique about this, is that any programming language's leadership should not be engaging in that kind of bad behavior. And any ill words coming from them about another language, should always be taken with a grain of salt and seen as likely bias.
It reflects poorly on any leadership engaging in that kind of bad and unprofessional behavior, and it eventually backfires on any project or person. People eventually notice it and figure out the foul things that have been or is being done, then demand accountability or walk away from the toxicity.
I will hopefully wait for comments from Ghostty, Bun or Tigerbeetle Devs.
On another point that is wroth mentioning, I hope Andrew will at least put it out publicly, IMO Zig isn't Anti-Rust. But it did attract the type of people who are not too happy with Rust. I dont remember a single time Zig came out to bash anything about Rust. It isn't Anti anything at all. Its goal is to be a decent C replacement as very high level assembly languages, aiming at Data Oriented Design with some interesting features, and extremely fast compilation speed. ( Which was the reason why I was interested in it in the first place. I miss Turbo Pascal )
Zig reminds me of the old school, traditional projects. It isn't perfect for everything, it never claims to be, if you like it, use it. If not, there are plenty of options out there.
At least Ghostty Dev seems to be enjoying it almost every day.
But as you say, there's no reason why Zig ought to be anti-Rust, both language are are fresh attempts at low level programming, both highly opinionated and with very different philosophies and trade offs and both language can cohabit peacefully (I've heard good things about using the Zig toolchain for cross compilation of C dependencies in rust projects, so the existence of Zig already has had a positive impact on the Rust ecosystem).
While he can get petty when talking about memory safety, he was never obsessed by Zig in any way, his tweet that ended up with Loris calling him “Coomer” among other names was a response to someone mentioning that Zig wasn't memory safe. I've never seen him mentioning Zig first on Twitter.
And on the other hand you have Loris, obsessed so much by Rust he can't help spawning in Rust threads or write dumb anti-rust rants on his blog…
(In fairness, I must say that Loris isn't even the worst offender, that title goes to M. Presler, who keeps spawning every Rust thread telling everyone who want to hear it that Zig is much better, despite having seemingly no stakes in the game (being a Java guy and having no public Zig contribution or even documented use of the langage). Sounds like the “Rust evangelical strike force” emotionally hurt a bunch of people so much they became lifetime haters).
I have not seen much of any anti-Rust sentiment in the community. There's a lot of people in the community who do Rust, like rust, and work on rust projects. If the Zig community has an anti-anything sentiment, it's against C++.
(You won't have to seek long in his HN history to find an instance of such behavior)
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.
Not trying to imply that’s an explicit goal (probably instead just a resource problem), but an observation
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.
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.
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.
If you keep up the development pace you're going to approach stability. Unless you're in a manic spiral of rewrites.
Making a programming language from scratch is a long endeavor when it's a one man project.
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.
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).
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).
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.
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.