Jamey Sharp (Jul 18 2023 at 16:35): Jamey Sharp (Jul 18 2023 at 16:35):As bjorn3 said, we'd love to get help improving Cranelift's documentation. Right now most of what we have is https://cranelift.dev/ and https://github.com/bytecodealliance/wasmtime/tree/main/cranelift/docs/. It would be nice to get closer to Wasmtime's documentation; the source for that is in https://github.com/bytecodealliance/wasmtime/tree/main/docs/ and it uses mdbook. Helping us set up mdbook for Cranelift would be a huge help even if you didn't write any new documentation in the process.
Endistic (Jul 18 2023 at 17:28):Yeah, I got a small mdbook thing setup, although I don't know how good it is, I don't use mdbook all that much.
https://github.com/akarahdev/cranelift-book
This is what I have so far. What do you think?
Jamey Sharp (Jul 18 2023 at 19:50):I like the structure you've outlined! It's hard for me to be sure exactly what you have in mind from just section titles but it looks reasonable.
One thing that occurs to me is that we have two kinds of documentation mixed together currently: docs for people who want to use Cranelift in other projects, and docs for people who want to make changes to Cranelift.
Something like https://github.com/bytecodealliance/wasmtime/blob/main/cranelift/docs/isle-integration.md or https://github.com/bytecodealliance/wasmtime/blob/main/cranelift/docs/testing.md is not interesting if you just want to use Cranelift, so those should go in a separate section of the book.
On the other hand, https://github.com/bytecodealliance/wasmtime/blob/main/cranelift/docs/compare-llvm.md is potentially useful to both audiences, so putting it in the introduction (currently section 1.4 of your book) is a good idea. It also is wildly out of date in places, but that's a separate problem…
https://github.com/bytecodealliance/wasmtime/blob/main/cranelift/docs/ir.md should probably get split into smaller chunks, many of which may help fill out various sections of your draft outline.
We should figure out how to arrange this material so that we can host the pre-rendered book somewhere. One unfortunate thing about GitHub pages is that as far as I can tell there's no way to serve multiple domains from one repository. The simplest solution is to keep the source for the book in a separate repository, and maybe we should start there; that's how the cranelift.dev and wasmtime.dev web sites work. But eventually it would be preferable to have the book source live alongside the Cranelift source so that it's easier to keep it up to date.
Endistic (Jul 18 2023 at 20:44):Sorry about the unclearness of the section titles, that was my bad. I tried to outline possible contents in SUMMARY.md including future chapters in the comments. And basically, I was trying to go for a patterm of learning a concept then applying it in code.
And for the two kinds of documentation, maybe the book should focus on using Cranelift (since that's a majority of the use cases), and we have another book (if possible) to store how to contribute to Cranelift.
And yeah, I agree. I think we should start out with a seperate repository for it.
Also, should we start a new topic specifically about the book? I feel like it would be better suited there so more people can see this instead of having to scroll through replies to this topic.
Notification Bot (Jul 18 2023 at 21:04):4 messages were moved here from #cranelift > Some JIT Questions (ft. an observation) by Jamey Sharp.
Jamey Sharp (Jul 18 2023 at 21:08):Oh, I didn't look for comments in the source. :sweat_smile: And a new topic is a good idea, done!
I'm more interested in improving the current state of things than in coming up with the perfect organization, and I suspect it's going to be easiest to start by keeping contribution instructions in the same book as usage instructions, so I'd suggest not trying to split them. We can always reorganize further later.
Endistic (Jul 18 2023 at 22:07):That makes sense.
In a little bit, I'm gonna try writing some stuff in the book. Probably gonna work on the first chapter.
Divya Mohan (Jul 19 2023 at 05:36):@Endistic : I'd love to tag team with you on this, if you want to divvy up the work. I have technical writing exp & could potentially help with structuring the content + the mdBook setup and/or anything else you need.
Last updated: Nov 22 2024 at 17:03 UTC