In considering developing a product using Zig, I was put off by a couple of things, which caused me to detour to commenting on your docs:
- The unconventional organization of the docs.
- It took 3rd-party docs to install, build, and run in my Linux environment.
I’d expect a doc site to mostly be about docs. By doc site, I’m referring to Learn ⚡ Zig Programming Language. Doc site navigation should be almost entirely in the left panel. In small sites, you rarely need menu tabs, although, Download and Source Code could certainly be justified as menu items. I wouldn’t expect News, Zig Software Foundation, and Join a Community to be on a docs site. A common docs mistake that startups make is conflating marketing material with dev/engineering content. I understand the tendency but it tends to obscure and distract from the content a developer is really interested in.
Thumbs up to choosing Hugo for your doc site (sort of). It’s what I recommend for startups, porting to a more English-major-centric static site generator later in a company’s development. If you view Learn ⚡ Zig Programming Language as an organization landing page, which I did at first, Hugo seems like an odd choice. Whatever tool corporations tend to use for their Home page might be better. But as a docs site, Hugo works. But you don’t actually use Hugo for your docs. Instead, there’s this strange langref.html.in file that is your real docs. I’d highly recommend porting that to Hugo .md files. The more conventional implementation might encourage more people to write for Zig docs instead of writing for their blogs.
As far as the auto-generated stdlib doc, I’m in agreement with mgavioli, above. The autogen vs. !autogen debate is decades old and no minds have been changed; it’s not likely to be resolved here. So autogen, as you do now, is fine, although I don’t think it gives you the best docs and the argument for maintaining currency with the code doesn’t tend to be realized in practice. Also, for something like stdlib, it’d be contemporary to have a 3-panel presentation, nav | content | example; see the DocuAPI Hugo theme.
It would be a good idea to document the stlib functions as you code them, not after the fact (although, the horse is already out of the barn). Something that might help is to not approve stdlib PRs unless the associated functions are also documented; but then you’ll need an autodoc style guide, as previously mentioned, to avoid a mess.
Here’s a proposed doc structure. I think it’s more conventional and modern than the current structure, making it more like what the reader expects to see. Tweaks are fine and expected but the core doc skeleton and vision must first be established. Of all the doc design objectives, these are the ones that are driving this proposed structure and associated process/tools:
- maintainability
- ease-of-authoring
- discoverability-of-content
- coherent doc style
Documentation ::=
Release notes
Quick start
Introduction
Learn
Compile and build options
Target environments
General application structure
Guides
Building with Zig
Testing
Memory management
[ tutorials per language feature, including ...]
Inline assembly
Package management
Undefined behavior
Compile-time
Runtime
C integration
Reference [use 3-panel layout: nav|description|example]
Zig language reference (just the syntax, with examples)
Builtin functions reference
stdlib reference
Environment variables
CLI reference
Keywords
Tools
Examples
Program style guide
3rd-party resources
A structured introduction to Zig
Ziglings
Zig on Exercism
The road to Zig 1.0
Zig and the relationship with LLVM
The 2nd- and 3rd-level headings are just to give the flavor of what goes in those sections. A key principle is that Reference content should be separated from How-to content. The How-to is in the Learn section. Guides is usually called Tutorials but almost everything that isn’t Reference is a tutorial. Using “Tutorial” as a broad, encapsulating term lets you differentiate the different kinds of tutorials: guides, quick starts, tech notes, recipes, etc. Along those lines, Learn is a node of Documentation, as Reference is, not vice versa. The menu item should be Documentation, not Learn. I’m not used to seeing it that way so it threw me off, initially. I’ll admit that Learn is becoming more common among companies as a main category and they include all their resources under Learn, but they also tend not to have very developed documentation. When I want documentation, I look for Documentation; it may be a cultural thing.
A stretch goal might be to also envision Cookbook documentation. I propose that because, other than actually using a system, a Cookbook is considered the best form of documentation for teaching a system. Each recipe encourages hands-on use of the system, covers error paths, and provides links to additional resources, in addition to walking the reader through progressive steps toward learning the system. It’s a stretch and lots of companies (and O’Reilly) that have a Cookbook doc don’t do it right.
Finally, some doc approach recommendations going forward:
- prototype the docs-only Hugo site using existing content (port langref.html.in to .md files)
- provide a clear visualization/nav of what kind of content goes where; reference-learn-etc. One benefit is that it makes it obvious what’s missing.
- integrate 3rd-party content if it’s better than official content
- create a minimal doc style guides for contributors; preferably based on Google Dev Docs Style Guide.
- use Vale, vale.sh, in the doc build to validate doc style guide conformance.