I can understand why people would recommend reading the source code of projects like Redis or SQLite (and here Zig's std lib) to learn, simply because the code quality is so high.

It's also not like anyone is proposing that there will be no documentation when Zig turns 1.0 (as if high quality documentation and code quality were mutually exclusive!) simply that Zig is not YET at that stage [1].

There's much to love about Zig, and it's always a good time to be reading code, and all the more so while it's growing and shaping because you end up with a deeper knowledge and understanding of what makes a great project great.

[1] Personally, I do find the language documentation to be pretty much excellent and the IRC and Discord helpful—hey, you might even bump into Mitchell Hashimoto also asking questions there. It's the std lib that's a little less, but again, that's in flux and files like `std/mem.zig` are enough of a pleasure to read and learn from. Zig's definitely a swell worth paddling.

Forcing people to read the code puts pressure on the code to be clean.

Not writing docs against an unstable API is a strategy to make it freer for the authors to change the API, possibly in sweeping breaking ways (for example allocgate).

It helps you to see what are the idioms, what does optimized production code look like.

Compare C++ and Go std lib and it’s easy to constate the difference in language goals that they have.

Almost every language has a dynamic array of some sort. They all do the same thing. They all have slightly different names. push / push_back / add / append. size / length / len / count. If you don't already know the name of a function then finding it is in a sea of text is very difficult and not fun.

Zig ArrayList: https://github.com/ziglang/zig/blob/master/lib/std/array_lis... C++ Vector: https://en.cppreference.com/w/cpp/container/vector Rust Vec: https://doc.rust-lang.org/stable/std/vec/struct.Vec.html

Sometimes I just want to see a list of functions. I can skim a list of 40 functions in seconds. Scrolling 800 lines of code and trying to pick out every single function takes much longer and is much more error prone.

I prefer to look up the source code either way, examples and the documentation can only get you so far.

But I know others much prefer reading docs over code.

I agree, reading the source is a good way to learn more once a person already know the language.

It can be great to help track down a bug, or learn about an obscure corner case in a function, or see more advanced idioms in use, but it's a pretty terrible and unfriendly way to learn a language in the first place.