Hi, I'm Loris from the ZSF.

I think this is a fair post overall given what it is: a log of what it was like for one specific person to use Zig for AoC for the first time.

I'll spend some words on some of the things mentioned and then add some more useful advice for forrestthewoods at the end.

From my perspective the complaints mostly were about now knowing things which had varying degrees of discoverability.

The first point in Day 1 about mixing optionals and error unions is an example of something very easy to discover (by reading the language reference), so I personally would consider it an unlucky mistake by the author.

The second point (how to print an integer) is about something way less easily discoverable than in the previous example. You need to learn about how to print, then about `fmt` and from there the only authoritative place that contains information about format specifiers is the doc comment of `std.fmt.format`.

This second example is the kind of thing that we're the weakest at communicating to people because it's not a feature of the language itself (so it doesn't belong to the language reference) and, while you could in theory find this stuff in the stdlib autogenerated docs, you still have the problem of having to discover first what to search for. This is especially problematic when Zig breaks away from what's common in programming languages. One example of that is the fact that Zig has no print statement.

I've given some talks and written some articles about how to do common things and find stuff in the standard library:

https://www.youtube.com/c/ZigSHOWTIME

https://zig.news

and, as the author metioned, Zig Learn is by far the closest thing we have to a "Zig book".

https://ziglearn.org

The problem with creating content for the standard library is that it keeps changing and it's not yet the focus of development. As the language matures more content is being created (just look at how many explainers are being posted to zig.news alone) but we're not yet in a position to invest into something like a book.

The author also mentioned issues with the autogenerated docs for the standard library. Those docs are currently incomplete and in fact greet you with this message as soon as you open them:

These docs are experimental. Progress depends on the self-hosted compiler, consider reading the stdlib source in the meantime.

I've seen some comments here about how recommending to read the source code is unhelpful. I vehemently disagree because of practicality first (if something is not documented elsewhere, then that's the best you can do) and second because reading the source code should not be considered something primitive that developers used to do before discovering fire.

We all should read more and write less.

That said, Andrew is going to help me start this week the work on a new doc autogeneration system based on a different design that the current (incomplete) one. I'll do most of the work while streaming on Twitch so if anybody has opinions, complaints or questions, you know where to find me: https://twitch.tv/kristoff_it

Going back to the post, there were also some impressions that we all fully agree with (and are working on improving), a good example being

> Bit-shifting is a monumental pain in the ass.

Yes, it indeed is. See: https://github.com/ziglang/zig/issues/7605

Ok, so, here's my advice to forrestthewoods if you're ever going to try Zig again:

[1] Interact more with the community if you want to be pointed quickly in the right direction. You mentioned the discord server so you already interacted with people. Leverage them more: ask questions in #zig-help and don't be afraid to ask why things are a certain way. You'll probably be way less annoyed by, say, ArrayList requiring you to access its `items` field to iterate, if somebody explains to you that ArrayList is a normal userland struct defined in the stdlib and that in Zig there are no "magic methods" that the compiler picks up to do iteration etc. Or maybe you won't be less annoyed, but at least you will know if something is intentional or if it's just something that we haven't gotten around fixing yet.

[2] Try to learn Zig doing something else other than Advent of Code. AoC doesn't really let Zig show it's potential because it doesn't ask you to do good software engineering. You're just supposed to write a script that gets you to the correct answer. Try instead doing a small project where you have to validate input, produce useful error messages to the user, clean up resources properly (sockets, memory, ...), etc. You will find that Zig will be much better in this second case. I'm saying this based on first hand experience btw, I've streamed the first 16 days of AoC from this year, you can find the recordings in this playlist: https://www.youtube.com/watch?v=wo580tbLSR8&list=PL5AY2Vv6Es...

I stopped after day 16 because I felt it the exercises didn't really help me showcase any big strength of Zig, so I started working on other stuff instead.