Since only a short time I test the Zig ecosystem. I’m a beginner here, while not being a rookie in software development otherwise. I started programming in 1982, did my first architecture of a complex software project in 1992. Before Zig I used ~15 different languages in projects, the last one being Rust.
Zig could be my favourite language for low-level programming. I could imagine to completely move away from C and C++ to Zig instead of to Rust. Zig is a piece of art.
But there is a blocker: the lack of specification and documentation.
I’m used to read documentation first. Then try out. Report bugs, which mean that the implementation does not comply to the specification. I struggle with Zig in this point.
Therefore, I suggest a project: Community Documentation. Let’s set up a Wiki for the community to fill the gap. Let’s have a Wiki to keep this up to date and centralized. And let’s have the rich text format of the Wiki the same as the one used for the official documentation, so texts can be re-used by the core team accepting them. Best would be a git based wiki engine, so even a PR could be created for the acceptance process.
Is there support here in the community for this idea? Shell I just set up such a Wiki and ask people to use it? How do core team members see this topic? Is this something wanted or less wanted?
ziggit has a dedicated topic for community docs! Docs
I think it could be made more obvious, though it is near the top of the sidebar. TBH I haven’t really used it, so I can’t speak to its quality, what little I have seen is good!
It probably does need more people using it so we can be notified of out of date sections sooner.
only Regular users can make new doc posts, but almost all users (excluding very new users) can edit existing ones, so updating them is accessible.
this is a good reminder that it exists, ya’ll should be linking to them, updating them and proposing new posts occasionally.
Is this meant to fulfill the mentioned purpose? Is this how documentation can be added by the community? Is there a process how this moves into the standard documentation? If all of this is already answered, where can I find information about this?
It is just community documentation. It is not in the same format official docs use, and it probably will not be integrated with official docs.
Documentation is just not a focus for zig at the moment, the language and std library (in particular rn) are in flux. And there are many things still planned to be explored, 1.0 will not happen until they are.
As they slow down, the docs should catch up and increase in quality.
ziggit is linked already, I don’t see why they would link to our docs specifically, but perhaps a mention that we do have some would be good.
No zig communities are official, we all do our own thing, but IME you will find more core team members here (including Andrew) than other communities. excluding the zulip, that’s not so much a community. But the platform of official choice for organising zig development.
I’m asking because possibly I’m a typical new user: I’m coming from somewhere else, I feel Rust like a corset or a cage, and I’m still searching for “but how can I avoid C++” – in my case since 1995
Zig is my chance to escape to a language, which supports me as a programmer. This makes me willing to give some support back. And so I can imagine could it be for other community members, too.
The alternative is, of course, how can I join Zig development so I can edit the official documentation and make suggestions / pull requests.
Zig is comparable old now for a project, which is not meant to be used in real-world projects. And in such real-world projects there are conditions needed, which lead to investment security when pushing workload into software based on Zig.
just make prs on Zig Software Foundation - Codeberg.org
they will ofc prioritise other things over docs, but if you show you know what your talking about I think they’ll accept them without much hassle. But that is much to ask of someone new to zig as you say.
I think the website is still on github due to technical issues. That is where the other docs are (excluding langref and std)
as much as andrew says that, there are quite a few that do use zig, mostly existing c projects using it as a build system, but the zig only/mostly codebases are rather popular.
But programming languages are big projects that take a lot of time, zig is still younger than rust was when it had its 1.0. But rust was rushed to get there by investors and is still undergoing active language development, though it is slow due to post 1.0 stability requirements.
I don’t think zig will hit 1.0 younger than rust did, probably will be at least a few years older.
imo, one area where Zig is lacking is not exactly documentation but learning resources. as a beginner, you have a unique perspective to bring to that problem. as you learn, you might consider making resources like tutorials or blog posts to help explain things that were particularly difficult for you to learn.
Personally I’d benefit a lot more from some sort of fixed set of complete and building “recipes” like:
how to read a file line by line
how to read JSON (something slightly more complex, like an array object objects)
a few build.zig examples on how to do certain common things
how to read command line arguments
I think there’s a wealth of this information even here on Ziggit and certainly on the internet, but it’s not centralized into the official docs and kept up to date. The set of examples would be small enough so that it’d be possible to keep up to date when Zig dev breaks it. I feel like there could be much value to be gained from focusing community efforts on one common section like this.
I aware of the Docs section here on Ziggit, but whenever I encounter some problem, I rarely find a solution from this section. I find clear, working code examples an easier way to get started on problem solving.
I realize that it’d probably suck if this would be part of the compiler team’s CI quality gates. But maybe the community could rally into to help and keep this updated for every Zig release.
