Comment by hardwaresofton

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.

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.

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

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.

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.

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.

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

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.

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).

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.

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.

> 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.

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.

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.

That is actually a valid point on expectation given the attracted people's demographic.

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.

> anti-Rust sentiment

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++.

This really struck a chord with me. Writing documentation is an act of explaining something to others. Explaining something to others is a great way to test your own understanding. If it's hard to explain to someone else, then maybe it's the wrong design.

If you don't through that exercise, you're much more likely to build confusing, difficult-to-use APIs.

100%.

Similar to how TDD forces you to first figure out the API of your code due to the test code being its first client.

Docs 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.

Zig as a whole is half-finished, should it be kept under wraps until it is ready?

There's a reason for the 0.x version number, if you can't live with breaking changes, don't use Zig yet. It's as simple as that.

Because the language is not stable at this point and hasn't reached 1.0?

Are you saying one should never make anything half finished available to the public? This post proves why it is valuable to do so, they are getting valuable feedback and a discussion on hacker news for free.

In 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.

You absolutely should expect documentation this early. The chances of quality documentation being added as an afterthought are not good. If proper documentation isn't part of the original goals after that time, things aren't looking well. Nobody is going to come and just write docs for months.

So zig isn’t a serious language. It’s just some trash apis thrown together.

[flagged]

You're conflating specs/RFCs with end-user documentation.

It's not a false dichotomy, it's a bandwidth issue. I'd rather the core team focus on stuff like incremental compilation.