Consider publishing an mdbook

[wmstack]

I believe that using Github files purely for organizing documentation is subpar. I find that most of the Rust books are far superior simply because they organize documentation in terms of mdbooks which are accessible in a separate website. Is it possible to create an mdbook under github.io that organizes the documentation for WASI?

[sunfishcode]

I've used mdbook in other projects and like it, though I don't have strong opinions about it versus other tools.

One current challenge is that a book implies an outline, and I don't think we currently have a clear outline for what WASI should document. WASI is currently transitioning to the wit format and associated tooling, and a lot of the content one might imagine wanting for a subject like "how do I use WASI" will end up being documented in the component model under subjects like "how do I use wit APIs", especially now that wit is officially moving into the component model.

In any case though, I'd be interested to hear what people think a good outline should contain.

[sbc100]

I think we should try to stick to tools that are used by WebAssembly core and/or other proposals/subgroups.

I would also worry that mdbook is quite specific to the rust community whereas on of the goals of WASI is to be language agnostic.

[sunfishcode]

I wouldn't rule out mdbook; it's just a tool, like Sphinx or Jekyll which are in use in other WebAssembly repos, which are of course implemented in a specific language, but the content is written in Markdown or reStructured Text.

That said, before we can evaluate any specific tool though, we need to figure out what will be in the documentation. That will significantly shape the decision about which tool is a good fit.