but what is wanted beyond zig.guide, zig std and the langref? that’s not clear to me at all.
3 Likes
For my part, I misread a comment above as saying zig.guide was out of date, turns out the rest of the sentence matters: “It never got updated for 0.14, but it was updated for 0.15.2.”
1 Like
(caution: shameless self-advertisement 
)
I’m currently working on the “Zelf Book” (I know, weird name, comes when you smash “self” and “zig” together).
It’s not in a state ready to be read by starters (I have barely finished the introduction to Zig by writing about the systems programming language history and introducing a small “hello world”).
But the goal is to make it a good community documentation page at some point.
4 Likes
I’ve been thinking about this for the last few days. I became more convinced that Markdown files in a repos is the best approach. The following is a little mock-up that I did, depicting such a hypothetical Zig manual in a programmer’s VS Code workspace:
The use of a git working folder for documentation purpose has many practical advantages over a website:
- No need for network connectivity
- No need to need keep open a web browser, a serous source of distraction
- Git operations are familiar to nearly all programmers
- They’re also intimately familiar with the editor/IDE of their choice
- Ability to search run regexp searches though the doc
- If the standard library is in the workspace (as depicted in the screenshot), a search would yield results both in the doc and std source code
- Having the doc displayed on a side-pane is super easy
- You can add your own notes to the doc the same way you can with physical programming books
The last point is what we’re counting on. We want to nudge people towards contributing to the documentation effort. I mean, they’re doing the hard work already. When people run into a blank page in the API doc, they don’t just throw up their hands and abandon their project. No, they would go into the source code and study it in order to gain the necessary knowledge. Currently, this knowledge would only show up in their own source code, in the form of code or code comment. If we make it easy for people to put this information where it belongs in the first place, i.e. in the Zig documentation, then people will do it. The page in question would already be open in an editor tab.
5 Likes
Interesting use of Gemini
interesting use of gemini. I like gemini’s terseness, and played with it a few years back.
But having tried to follow Brian Kernighan advice (after studying his Unix for Beginners in the mid 80’s) to make lines short and break them at natural places, that just seems to make more sense than using gemini’s long lines. This is especially the case if you work with any version control system/diffing tool on your (evolving) texts.
I understand the idea about the long lines (at least I think so), but concatenating lines and having an additional way to indicate hard-wrapping (that isn’t triple back-quotes and it’s mono-space font requirement), would have been better solution, without making a client noticably more complex. Too much of the burden of simplicity provided with gemini now lies with the author IMO.
1 Like
Yes and no. You usually have a standard line length limit in other formats. Often, the convention is to do 80 characters per line at most (though I prefer 96 because IMO that number is more beautiful ).
When you then rewrite a part of the documentation, it is usually not matched to those 80 or 96 characters per line. So you’ll have to adjust it. When you have the textwidth option set in Vim (as I have for markdown files), you can just first mark the lines you want to “re-flow” in the visual line mode (shift+v), and then use the command “gq” to re-create that line limit. Although that effort is small, “just” using long lines is a smaller effort in my opinion.
I don’t really want to turn this discussion about documentation in Zig into a discussion about short and long lines, so I’ll leave it at that.
I’m all in favor of this. Currently with my project automating building LFS that is exactly what I did. All the docs are in markdown in a doc dir at root level. Then I made a template based of a man page.
In a previous life I was a docs professional.
In my markdown docs, I put each sentence and occasionally long clause on separate lines. Docs are meant to be read in rendered form. The source format is for writing and content management (not primarily consumption) , meaning friendly to reviewing in diffs, which line-per sentence is very useful for.
Good to establish editorial standards regarding spelling, voice, formatting, links, pull request reviews, etc.
[ed]. Fixed wrapping column in Markdown source is an antipattern. Lines should be grammatically coherent atoms (for review/diff). Long lines are fine – that’s why your editor has word wrapping. If your sentences are getting that long, they likely need to be broken up anyway for readability.
6 Likes
Let us not forget that we are software engineers, and the machines serve us (for now) :).
Incremental software improvements are possible, and benefit everyone. Here are a few ideas:
- Profile how fast zig std opens, and implement optimizations. It is painfully slow after download from the internet.
- Similar to how zig std opens in the browser from your zig executable. Implement the same for a zig langref command.
- Could improve markdown rendering support for doc comments in zig std. Like supporting tables, etc.
- Could improve how links to other files are resolved in autodoc.
- Could improve the build system api documentation on how to add autodoc.
- Add a mechanism to compile full source files as part of autodoc, instead of just doctests (similar to how the lengref has a test / compile system that checks example files)
This is a great way to put it. The main language documentation is pretty good, but I’m sure it’s overwhelming for most people to just drop in and read it top to bottom.
Our target audience are programmers, people who stare at source code all day long. The absence of typographic decorations is a minor issue. Hey, stuff is more WYSIWYG unrendered if you think about it 
Keeping the Markdown files readable does mean foregoing hyperlinks. That’s a more substantial loss. I think the trade-off is worth it, especially since it reduces the work a contributor would need to do.
Better readability will also be helpful when we merge the doc for an upcoming release into the doc for the current release. Just prior to a new release, both branches will have accumulated many changes. Not having embedded links makes it easier to see what has actually been modified.
No manual line-wrapping should probably be made a hard rule. Otherwise it’s going to happen. I do this out of habit all the time, just because that’s what code comments require.
1 Like
Heeding your advice I took a look at number 1 
The profiling I did wasn’t very rigorous, but the numbers should be fairly accurate.
Running zig std locally (v0.15.2):
| Run | Compile zig std |
Compile main.wasm |
Serve files | Run main.wasm |
Total |
|---|---|---|---|---|---|
| cold browser & zig cache | ~6s | ~8s | N/A (fetched while main.wasm compiles) |
~300ms | ~15s |
| cold browser cache | N/A | N/A | ~300ms | ~300ms | ~600ms |
| warm browser cache | N/A | N/A | ~300ms | ~300ms | ~600ms |
From https://ziglang.org/documentation/0.15.2/std/:
| Run | Serve files | Run main.wasm |
Total |
|---|---|---|---|
| cold browser cache | ~1.8s | ~400ms | ~2.3s |
| warm browser cache | ~600ms | ~400ms | ~1.1s |
Most processing time is spent in main.wasm by std.zig.tokenizer.Tokenizer.next() via Scope.lookup() in main.wasm.Walk.expr() and std.zig.Ast.parse() in main.wasm.Walk.parse().
Most network time is spent fetching sources.tar.
(Note main.wasm is called autodoc.wasm here)
1 Like
I always use[this style][tsty] in my own writing. It doesn’t interfere with legibility to any significant degree, in my experience.
[tsty]: https://really-long-link.example.com
Here’s the thing: Ziggit has a Docs category, and guess what? It parses Markdown, and the result is community editable. So I think all this talk of “we should have a wiki” is a case of people wanting to eat bread, but not wanting to grind flour.
Understandable, but no flour, no bread.
3 Likes
If I understand it correctly the docs category is just a collection of threads. A wiki would paint a more consistent picture. It would be one place with a structured set of pages instead of a loose collection of threads with answeres for correcting or specifying OPs.
It’s more than that, actually.
I’ll grant you that this fact is not especially discoverable.
3 Likes
Thank you. I had a closer look. I did not notice that the Original posts were repeatedly updated. This is indeed more than a collection of threads.
1 Like