Some of this has also been said or hinted, but, two cents:
I’ve often found much of the terse in-code documentation to be excellent, maybe moreso, sometimes, for the terseness. I have to read it twice, but I’ve often been surprised at how much is said in so few words - some of the core developers have shown a nice knack for clarity and conciseness. Thank you developers. I’m sure it’s not always, but….
CODE is great documentation. I’ve heard this a lot over the years, but it depends a lot on the code! In some cases, code is NOT good documentation, but I’ve found a lot of zig (std code, for instance) to be very legible. Lots of short implementations that are pretty easy to “get”, once you’ve got the hang of some of the language idioms (which can take a bit - it did for me). There is a convenient “src” link at the top of all std doc pages that takes you directly to the code, if that’s more convenient than using your editor. Often only HALF of the comment atop some function is shown in the documentation - you see the whole comment in the code itself, and then the code itself is helpful to boot.
Many have been writing recipes and such. I even tried my own first bit, recently, and hope to do more - it helped me understand something much better than I had before. Unfortunately, YMMV with much of this community documentation just because the language is shifting under our feet, so it becomes deprecated rather quickly. This is, as it’s been said, merely a reminder that we’re working with something still so nascent.
EDIT: all that said, I still agree with all the sentiment - I’m looking forward to better documentation in the future, too!
At least specification is required. Otherwise it is impossible to say if something is a bug, which needs to manage a workaround, or if something is correct.
A public git repo holding Markdown files would inspire more confidence, I think. People aren’t so keen on contributing to a mystery database that might disappear tomorrow. We can provide a small program that allows users to run a local web server off a working folder of the repo. It’ll import everything into a SQLite database on program start so that users can run searches on the contents. They can also upload these static files to a CDN if they feel like being the host of a Zig documentation site.
I totally agree that a set of good quality updated examples for common tasks would be splendid. I did a Discrete Event Simulation code with Zig for an assignment at Uni, and my assignment partner could not figure out how to open a file and read its contents due to the Io change (version 0.15.2) and he was also a quite technical person.
I really think this could benefit lots of new users and beginners, and could help reduce friction :))
I think that’s a valid concern, but the best man pages I’ve ever used are from OpenBSD and they also generate quite readable web pages.
edit
Counter to my own point: wikis are accessible to writers, which is pretty important in these early days while it’s still being created. Plus a FAQ or an architectural topic might not fit as easily into man pages.
(I may have got a little excited picturing mapping the existing Zig docs comments system into man pages.)
What I wanted to say is that everyone knows how to navigate a good website but bot everyone knows how to do so for man pages.
I have a few of my friends in my major (no cs or programming but math) that don’t know anything about programming but I helped them learn zig. If the docs required man pages, I feel like I’d have lost one or two on the way.
I’m not sure if I’m clear as english isn’t my native language ;-;
I’m old style, and would prefer to be able, 100%, to work even when I’m offline. The mythical “work while in a tunnel, a plane or an island”, so to speak. This is why I balk at requiring any sort of web site just to read docs.
This. IMO what we really miss is having codebase as the doc source, not the other way around.
Unfortunately it requires a signaficant reconsideration of the current docs update approach.
move all the hand written doc to the codebase comments
make doc rendering from source comments
if we are talking about higher level samples zig cookbook is a great resource, but worth updating it in the community, I would be happy to see it advertised on zig doc page so people could use it and contribute into it
Here are my 2 cents:
I don’t think this will be solved by a bunch of people showing up one time and leaving their bike shedding technical solutions to a social problem, expecting somebody else to step up.
If people want the things mentioned here to happen, then somebody needs to volunteer themselves to be the leader of that project (which requires that they have the time and dedication for a continued effort, not a one time thing; and are able to withstand the pressure to add every feature imaginable), once they have done that, they can talk to @kristoff and the core group to establish how to best help support Zig in documentation matters without becoming a distraction to the development efforts, or producing stuff that can’t be merged into the main line, because it doesn’t follow the same vision that the core group has for the language and its documentation.
So roughly:
volunteer yourself & make an initial plan
talk to core group & establish a plan
rally community around you
figure out technical details
I think all other approaches will just result in either yet another obscure community version of documentation (which I am personally fine with) or nothing at all.
I don’t think that starting with point 4. will lead in a productive direction.
This is just my opinion I don’t know if the core group would agree, there is also another viable approach that was already mentioned by @vulpesx:
My perspective is that a lot of these “I want better documentation” topics are by people who want the finished product, but are you willing to make it happen?
I’m in favor of having the man pages. Then they could be made accessible online like the linux-manpage project that provides the manuals for the Linux kernel and glibc standard library.
Naturally they’re the ones who are most likely to want them, because it would make it easier for them to learn the language. (Myself included) Though we’re not the ones in the best state to write said documentation.
Almost 100% yes, starting w/ # 4. technical details feels wrong but 3. Rally community - depends on people thinking their needs will be met, so these discussions do tell us a little about that, e.g. that some of us value supporting both web and 100% offline/terminal use, or having a leader that maintains focus & minimizes noise.
Your #1 though: Yep yep yep. I think this is bike shedding until somebody steps up and offers a platform.
