Hey all, per the last SIG meeting I've opened a draft PR to the wasi.dev repo: https://github.com/bytecodealliance/wasi.dev/pull/21
Have a look and make suggestions! The gh-pages branch will eventually just want the build output, but I figured it's easier to edit the Markdown source. A couple notes and caveats: my roots in the ecosystem are nowhere near as deep as y'all's, so please hack this up and correct whatever is off! I took a lot from Pat and Bailey's notes...on the whole I think this should be friendly-but-coolheaded documentation, but I really liked the bold big picture quality of some of their language and tried to keep that energy in the intro. Look forward to everyone's feedback.
Thanks, @Eric Gregory! It looks like a deployed instance of your PR branch of wasi.dev is at http://ericmg.com/wasi.dev/, which I'm browsing now.
Following up on our 3/13 meeting, I've opened a draft PR with a Docusaurus implementation of the site revamp: https://github.com/bytecodealliance/wasi.dev/pull/23
Thanks, @Eric Gregory! Would it be possible for you to deploy your docusaurus branch to gh-pages so we can browse it in published form?
@David Bryant Here you go! https://ericgregory.github.io/wasi.dev/
I like the new look with Docusaurus and the navigation capabilities it provides.
In browsing through the current wasi.dev I often find I've ended up in other (non-WASI) places, especially the wasmtime documentation. What are your thoughts on how much of that we should absorb into the WASI book and perhaps then have those other materials just refer to the (new) WASI book? Relatedly, the current wasi.dev has a "For more documentation see (link)" which points into the wasmtime docs for a list of WASI documents.
@Pat Hickey who is best to be the reviewers for the new site layout? Eric has a great first iteration in PR.
Good question - I'm not working right now so it’s not me. Anyone on the TSC or board is definitely qualified to review. @Dan Gohman is an authority on this as well. I trust your judgement on whoever you ask for help on this
David Bryant said:
I like the new look with Docusaurus and the navigation capabilities it provides.
In browsing through the current wasi.dev I often find I've ended up in other (non-WASI) places, especially the wasmtime documentation. What are your thoughts on how much of that we should absorb into the WASI book and perhaps then have those other materials just refer to the (new) WASI book? Relatedly, the current wasi.dev has a "For more documentation see (link)" which points into the wasmtime docs for a list of WASI documents.
This is a good point David. I'm back from travelling and will add similar comments to the review today. While the documentation effort is facilitated by the BA SIG, the WASI docs should not be BA specific.
@Eric Gregory it's a little challenging to add review feedback in the rendered html. I'd like to shift the focus away from the BA for wasi.dev at least on the intro page. Will you move this paragraph to the Contribute section?
The Bytecode Alliance is a community comprised of many individual contributors and 30+ companies involved in the WebAssembly space. This site is a community effort supported by volunteers through the Bytecode Alliance's Special Interest Group for Documentation. If you would like to get involved, you can find us on the SIG Documentation channel of the Bytecode Alliance's Zulip server.
Then this is ready to go. Editorially, I'd like us to keep this runtime agnostic going forward.
@Bailey Hayes Sounds great -- I've made these updates to the PR!
Hey there! I'd like to help out where possible.
Are there any plans for adding WAT examples to this site? That would have been a great help for me personally in understanding WASI. This goes for most WASM-based docs sites, honestly. Having guides entirely around language-specific tools are barely helpful conceptually and only practically useful as long as tools don't go out of date (which can happen quickly in a fast growing system).
As an aside, my background is in web development with a lot of emphasis around internal documentation tooling at previous companies. Let me know where I might be able to lighten the load.
Hey Calvin! We’re planning to talk about focus areas for resources like wasi.dev at the next SIG Docs meeting on June 5 if you’d like to attend and discuss! I definitely think it would be useful to build out more material on reading and using WASI interfaces. You can find more about the meeting schedule and attending on the GitHub repo: https://github.com/bytecodealliance/meetings/blob/main/SIG-Documentation/2024/docs-06-5.md
Last updated: Dec 23 2024 at 13:07 UTC