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