[hardwaresofton]

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]

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.

[virtualritz]

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]

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.

[SoraNoTenshi]

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.

[felixgallo]

Zig is just getting started and came way after rust.

[oblio]

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]

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.

[aDyslecticCrow]

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.

[mikepurvis]

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.

[throwawaymaths]

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

[tel]

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.

[foxes]

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]

Just because and AI produced it doesn't mean it is slop.

[ioasuncvinvaer]

But it is a pretty good signal of low quality.

[BobbyJo]

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.

[pixl97]

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.

[keyle]

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]

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]

I don't live in that universe! I thanos flicked it off!

[skupig]

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]

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

[kristoff_it]

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

[mirashii]

> Maybe, or maybe the fact that Zig is a small independent project with limited resources has also something to do with it

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

[hitekker]

Much of that bad blood comes from how Rust's leadership attacks other programming languages, online and offline.

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.

[zozbot234]

> infamously declared zig was "a massive step back for the industry"

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

[baranul]

There are a couple things about that take, that many would say deserves push back on: (1) Rust supremacism has been aimed at many other languages, not just Zig in particular. It's been a wide spray. (2) Many would say that Zig's leadership has done similar to what you are saying about Rust. Very clear examples have been the relentless unleashing on Vlang and its creator, and to a lesser extent on C3.

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.

[littlestymaar]

“Zig not being memory safe” is what's being called “a massive setback for the industry”.

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

[mi_lk]

https://news.ycombinator.com/item?id=4467200 is not about Go/memory safe btw

[littlestymaar]

> Rust supremacism.

I can't believe you really wrote that.

[baranul]

This Zig victim complex, smells of clear hypocrisy, as can be easily seen by their swipes and harassment of other programming languages, like V (Vlang).

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.

[littlestymaar]

Loris really isn't a person worth engaging with honestly, don't waste your time.

[hardwaresofton]

Personal attacks like this have no place on HN.

[mirashii]

I just wanted to clarify that I point this out to say that there was a real opportunity in this thread to try to push back on the language wars perception. To me, good community management would be taking the opportunity to say:

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

Instead, we got a shallow dismissal and redirection, which unfortunately starts to look like a pattern, especially when coming from a person who's in a leadership position in the community being discussed.

[adwn]

> […] Zig was still using the bootstrap compiler written in C++ that would not free memory […]

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?

[messe]

IIRC, it was a performance thing, and it's not an uncommon pattern in CLI tools. Freeing memory can actually cost you performance, so why not just let the OS clean up for you at exit(2)?

[adwn]

> IIRC, it was a performance thing […]

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.

[pjmlp]

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]

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

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

[pjmlp]

Thanks for clarification.

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.

[brodo]

Here is another comment on the whole Handmade-Kerfuffle from one of the presenters:

https://wiki.xxiivv.com/site/2025.html (the entry under 19b)

It seems this was a right vs. left (or liberal) split.

[deagle50]

more like old school lib vs "new left"

[secondary_op]

Unfortunately for everyone, people like you tie their entire identity and income to specific technologies, movements, or communities—becoming deeply tribal in the process. When something or someone undermines their sense of security—even with constructive criticism—they react defensively, often to the point of ignorance.

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.

[baranul]

If you didn't know, Casey has made comments on a YouTube video, that he does not like Zig. His review of Zig, was that it's a language that he rather not use and would not recommend.

[bnolsen]

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]

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.

[ksec]

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.

[littlestymaar]

I don't think Andrew is anti-Rust. But Loris, whose hn profile says he's “vp of community of the zig software foundation” is as anti-Rust as you can get: he's pathologically obsessed by Rust and spent significant amount of energy outright insulting Rust maintainers here or on Twitter (when he's not buzzy writing anti-Rust rant on his blog).

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

[geodel]

Huh, it all started with a Rust developer ceaselessly picking on Zig been memory-unsafe on social media. It would be one thing to write some technical post and be done with it but this obsession with Zig by Rust dev was infuriating to put it mildly. The same dev was very anti-Go in past and would post endless comments on Go here and elsewhere.

[littlestymaar]

I used to follow pcwalton on Twitter back then (before it became a nazi bar) and that's a complete mischaracterization.

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

[TUSF]

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

[littlestymaar]

Tell that to the “VP of community @ zig software foundation” who spend a significant fraction of its time insulting Rust maintainers or mere users here or on Twitter when he's not busy writing anti-Rust rants on his blog.

(You won't have to seek long in his HN history to find an instance of such behavior)

[hardwaresofton]

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]

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.

[brabel]

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.

[hardwaresofton]

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

[LambdaComplex]

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]

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.

[tialaramex]

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.

[LambdaComplex]

Huh, I actually expected there to be a bigger team working on it. In that case: I'm really impressed.

[HumanOstrich]

What's the benchmark for how long something can be pre-1.0? Seems like a nonsense argument.

[Dylan16807]

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.

[yxhuvud]

Something can be pre-1.0 as long as there are no stability guarantees.

[pharrington]

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.

[throwawaymaths]

https://github.com/ziglang/zig/milestone/2

[littlestymaar]

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.

[sshine]

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.

[chrisandchris]

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]

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

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

[BobbyJo]

Tests very often don't tell you the right way to use something, especially when you're talking about IO libraries. Examples themselves often don't even show the "correct" way, but rather just a way that will work in ideal circumstances.

[rjh29]

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]

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.

[jakobnissen]

There 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

[simonask]

I tend to actually disagree with this attitude, because I see writing documentation as really effective "rubber-ducking". If it's hard and time-consuming to properly document, it's probably hard to use, so extra effort should be spent to actually justify the design, not least to yourself in 6 months. If you can't justify it, it's probably wrong.

[kelnos]

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.

[throwawaymaths]

> you're much more likely to build confusing, difficult-to-use APIs.

have not found this to be the case with zig in general. you could easily make the opposite argument, that documenting things (especially quirks) can give you license to build confusing APIs.

[ioasuncvinvaer]

I think some documentation and a handful of examples would have helped the author of the article. How is the experience when porting to the new standard library improved by not including documentation?

[CRConrad]

> > you're much more likely to build confusing, difficult-to-use APIs.

> have not found this to be the case with zig in general.

Dunno how general it is, but TFA we're discussing here contains an example, so AFAICS it seems at least a little too common.

[pmarreck]

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.

[crote]

On the other hand, not writing documentation also has a cost.

Code is rarely written from start to finish in a single session. Would you rather spend 5 minutes before you do a git commit to write down some very basic documentation, or spend an hour rediscovering it when you pick up development two weeks later?

Nobody is expecting extensive and well-polished documentation here, but is a "Flags X, Y, and Z are mandatory, buffer A is required: I tested with 10MB, smaller might be fine too" really too much to ask for?

Is the time you saved by not writing that one line worth someone else spending several hours figuring out how to do a "hello world"?

[7bit]

Your argument implies that good documentation is not an improvement, which of course is wrong. It also belongs to the task of improving code. Why would you move away after half-assing the API, when you can add the docs and whole-ass it instead?

[hardwaresofton]

This 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]

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.

[aDyslecticCrow]

Then they should not have relead the new api at all. Why release half finnished library.

[flohofwoe]

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.

[aDyslecticCrow]

Breaking changes and limited support is one thing. But docs is not something you add at at the end. Lacking docs and Lacking tests is code that should not be released.

They target embedded c market. Limited support and features is expected and common. But being lax with docs and testing is not acceptable.

[flohofwoe]

> But being lax with docs and testing is not acceptable.

First: Those two things are not the same. The Zig stdlib and compiler have tons of tests, and it's actually quite rare to stumble over implementation bugs.

Second: I'd rather take no docs at all than per-function or per-type doc-headers which just repeat what the code does in natural language (and then may quickly get stale). Some parent wrote about generating docs with an LLM which is just a laughably bad idea, since even with perfect results you'll just get a redundant reiteration of what the code below does, just in imprecise human language, it would literally just be redundant noise.

Documentation mostly makes sense up on the systems level to explain high level concepts, not as 'this function does this and that...' level, this information already exists in much more precise form in the source code below the doc header.

But this sort of high level documentation doesn't make sense as long as a project is in the experimentation phase, and Zig is still one big experiment.

[aDyslecticCrow]

I fundamentally disagree on code readability. A comment on the function header can save an hour of code reverse engineering for a complex library. Reading code is a last resort, and stale code docs is itself a red flag.

This post itself is a great example. The code is not self explanatory unless you understand the library below. So if this was library code; you would have to reverse through two abstraktion walls to understand it.

And as for high level documentation... it would be very helpful to have that DURING the development process to discuss the implementation, and quickly get people up-to-speed in the plan during code review. Id write that before the code.

I mention tests, because they are 10x more work to write than docs. So if the developer skips out on docs, my trust in their testing is also destroyed.

[sureglymop]

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.

[viraptor]

There's an alternative of being much more up front about the status. For example the project page doesn't really say it's unstable/experimental. It only says "Zig has not yet reached v1.0" on the "getting started" page, which doesn't really mean that much - for example Putty is still at 0.83 after 26 years.

If the project invites me to use it "for maintaining robust, optimal and reusable software." without putting "super unstable, we don't even care about docs" on the same page... that's also saying something.

[throwawaymaths]

AIUI the team has a geberal consensus on what is left tp do before 1.0, there's even a tracking list of requirements on the github.

if you have that attitude about docs, then likely you are being gatekept from the project until it hits 1.0.

[HeartofCPU]

Very good point

[wordofx]

Na. It’s flat out laziness. Don’t make excuses. Either write docs or stop worrying code.

[pharrington]

I'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]

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

[ulbu]

i 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]

You can’t expect documentation this early. The new interface was just released.

[viraptor]

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.

[rjh29]

It's pre-1.0 beta. Nothing has been 'released' yet .

[viraptor]

That's ok. "It's an unstable, experimental, early version." is a valid explanation. GP put the lack of docs and the new interface together, which... isn't an excuse.

[geon]

That Zig is pre 1.0 is a given. Not sure how you could take my statement as ”even post 1.0 releases don’t need docs.”

[speed_spread]

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.

[geon]

Zig is open source, so the docs are pretty much a wiki. You can spend 5 minutes.

[wordofx]

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

[maxbond]

It's a serious language, it's just not a stable language yet.

[0x696C6961]

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

[DannyBee]

Only in a world where features are made without thought. Documentation is not just for your users. Writing the development documentation helps you make better features in the first place.

The zig users on this thread seem to not understand this, and all seem to think documentation is a thing you write later for users when everything settles down. Or is somehow otherwise "in the way" of feature and API development speed.

That is a very strange view.

If writing developer documentation is having serious affect on your language feature velocity, you are doing something very wrong. Instead, writing it should make things move faster, becuase, at a minimum, others understand what you are trying to do, how it is going to work, and can help. Also, it helps you think through it yourself and whether what you are writing makes any sense, etc.

Yes there are people who can do this all without documentation, but there are 100x as many who can't, but will still give high quality contributions that will move you along faster if you enable them to help you. Throwing out the ability to have these folks help you is, at a minimum, self-defeating.

I learned this the hard way, because i'm one of those folks who can just stare at random undocumented messy code and know what it actually does, what the author was probably trying to do, etc, and it took years till i learned most people were not like this.

[0x696C6961]

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

[CRConrad]

No, AFAICS GP wasn't conflating anything. Why would you think they were?

[dns_snek]

That'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]

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

[dns_snek]

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

[0x696C6961]

"No documentation" was never presented as an option. Documentation exists. By treating "insufficient docs" as "no docs", you're the one making the false equivalency.

[dns_snek]

> Documentation exists

Where does a beginner go to learn how to use the package manager these days? It looks like they still won't find any clues in the "Learn" section of Zig's website.

There's a promising page titled "Zig Build System" in there which references a "Package Management" section, but when you click on it, it doesn't exist!

[geon]

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