4 ms·

How about improving documentation? Last year I tried Zig and the documentation was abysmal. The majority of standard library functions had no documentation. The

How about improving documentation? Last year I tried Zig and the documentation was abysmal. The majority of standard library functions had no documentation. The sparingly few examples that exist on the webpage didn't work with the current Zig version and more. I say that as a Zig sponsor who wants to see research and innovation in the systems programming space. Documentation is maybe not as sexy as replacing LLVM with your own backend, but sorely needed.

YuukiRey 3y ago
It might be a bit early to invest in the documentation of APIs and implementations that are still subject to significant change. For the stable parts of the stdlib this would indeed be a very welcome change and would also lower the barrier for people to use Zig.
Laremere 3y ago
As a small tip, I have found that the [src] links in the documentation that go to the source to be very useful. Zig prioritizes readability, and often I can find the answer quickly when the documentation is lacking. That said, yeah it's not great. This talk gave some good reasons for doing things in the order they are. Spec and documentation are best done after the target has stopped moving, and it's simply going to be awhile until that happens.
flohofwoe 3y ago
There's still too much change in the stdlib APIs to make 'tutorial style documentation' worth the effort, because they will most likely be outdated within a couple of weeks or months. There's an auto-generated documentation here (with many parts still 'under-documented': https://ziglang.org/documentation/master/std/ https://ziglang.org/documentation/master/std/ ...but the best option is usually to just look right into the stdlib source code to figure out how things are supposed to work (IME stdlib code is generally easy to read, and easy to find - and with the VSCode ZLS plugin you can also directly lookup the stdlib source code by clicking on a stdlib type or function call). For larger-scale changes, keep track of Github issues and PRs (those are usually extensively documented) or ask around on the Discord, folk are actually very helpful there.

YuukiRey 3y ago

It might be a bit early to invest in the documentation of APIs and implementations that are still subject to significant change. For the stable parts of the stdlib this would indeed be a very welcome change and would also lower the barrier for people to use Zig.

Laremere 3y ago

As a small tip, I have found that the [src] links in the documentation that go to the source to be very useful. Zig prioritizes readability, and often I can find the answer quickly when the documentation is lacking. That said, yeah it's not great. This talk gave some good reasons for doing things in the order they are. Spec and documentation are best done after the target has stopped moving, and it's simply going to be awhile until that happens.

flohofwoe 3y ago

There's still too much change in the stdlib APIs to make 'tutorial style documentation' worth the effort, because they will most likely be outdated within a couple of weeks or months. There's an auto-generated documentation here (with many parts still 'under-documented': https://ziglang.org/documentation/master/std/ https://ziglang.org/documentation/master/std/ ...but the best option is usually to just look right into the stdlib source code to figure out how things are supposed to work (IME stdlib code is generally easy to read, and easy to find - and with the VSCode ZLS plugin you can also directly lookup the stdlib source code by clicking on a stdlib type or function call). For larger-scale changes, keep track of Github issues and PRs (those are usually extensively documented) or ask around on the Discord, folk are actually very helpful there.