Documentation is the weak point of Zig – this problem must be solved

Brainstorming
,
21

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!

3 Likes
22

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.

23

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.

2 Likes