bytecodealliance
Clarify more concisely how concepts relate to each other
I think we should still add this in as a TOC for the design section. This needs to be rebased, filenames updated, and this added to summary.md such that it is the top level for the "Understanding the Component Model" section
@itowlson can we revisit this and see if we can fit in this glossary? It is a great overview for someone who is learning what WASI, WIT and the component model are. I think the package, world, and interface definitions are already covered in the WIT explainer but having a TLDR of them somewhere (maybe the top of the WIT document) could be helpful.
@itowlson what are your thoughts on moving this to the Introduction page (almost as a preface to help readers know where to go with these new terms in their lexicon)?
@kate-goldenring I feel like it might be overwhelming in the intro - create the feeling of "you have to know these before you can read the book" possibly. I am no longer quite sure where it would go though. It could possibly be kludged in on the "why the component model" page, even though it's more "what" than why, perhaps?
Maybe this should go under the Reference section under a new definitions page?
This is a great addition--I think the introduction is the right place for this, since these terms are ultimately critical vocabulary for understanding what follows.
Hey @kate-goldenring @itowlson I've taken a stab at updating this PR and also adding the new information to the Introduction -- thoughts?
@vados-cosmonic Thanks for picking up this languishing PR! However, my objection to putting it in the introduction remains the one I mentioned in https://github.com/bytecodealliance/component-docs/pull/64#issuecomment-2791052373 - I feel like this is simply too much to absorb on a page that may be readers' first encounter with the book.
The paradox of it is like if you know what these things are and how they fit together, you don't need it; and if you don't know, then it scares you with half a dozen things explained in terms of each other. And so I am not sure if it is a set of signposts (at the beginning of the concepts section, giving you context for the things you're about to run into) or a recap (at the end of the concepts section, drawing it all together).
Or super-vague brainstorm alert maybe it's not (only) a recap. Maybe the pages of the concepts section include the relevant pointers. Like end the "components" page with a boxout along the lines of:
Want to know...
- ...how components expose and consume functionality? Check out the Interfaces page.
- ...how components specify the environment they need in order to run? Check out the Worlds page.
- ...how components are published and distributed? Check out the Packaging page.
(sorry I know these are bad)
and that way the reader can maybe form a sense of the relationships as they navigate around rather than having to take them in all at once. (And maybe we keep a document like this as a recap so that readers can review and confirm their understanding, and can revisit to refresh their understanding in one place.)
Sorry I know I am being vague and indecisive on this. The above is very much thinking out loud and I realise it wombles off in a different direction. Maybe we are indeed better off just getting it in and iterating.
Thanks for the thoughts here! At the very least we've got an updated section and a rebased PR, so hopefully we're one step closer to merging!
or a recap (at the end of the concepts section, drawing it all together).
Or super-vague brainstorm alert maybe it's not (only) a recap. Maybe the pages of the concepts section include the relevant pointers. Like end the "components" page with a boxout along the lines of:
This gives me a thought -- what about actually this information part of a new section header? Something like "How the component model works" or "Concepts", and having the current sections ("components", "WIT", etc) be subsections under that?
This information would be a good start/overview to a "concepts" section. That's kind of like a recap (a precap?)
@vados-cosmonic That seems well worth exploring! When you say "a new section header," are you thinking e.g. a new page after "Why the Component Model", and then the bullets from the current PR absorbed into a more prosey, explanatory style kind of thing?
Yup! Something like:
1. Introduction
2. Why the Component Model?
3. Component model concepts <-- new content goes here
3.1. Components
3.2. Interfaces
3.3. Worlds
3.4. WIT
3.5. Packages
We do our section headers a bit inconsistently right now but this is the rough idea of what the left hand side menu would look like.
@vados-cosmonic Your proposed structure looks promising to me. My bullets will certainly need expanding to make it work but I feel much more comfortable with that than with having them in the intro. @kate-goldenring if you're not sick to death of this issue what do you reckon?
I feel like the WIT reference it different from the other sections in that it is quite stand alone and not a conceptual explainer rather a reference. What about the following:
1. Introduction
2. Why the Component Model?
3. Component model concepts <-- new content goes here
3.1. Components
3.2. Interfaces
3.3. Worlds
3.4. Packages
4. WIT Reference
Hey @kate-goldenring that certainly looks good to me! Will rework this PR to match that layout.
IMO we do have a References section where the WIT reference should probably go, but IMO we should also have a separate introduction to WIT (more "why" and "what" than "how"), but that's for another day :)
I've made the changes! Hopefully we can take a quick look at it in the meeting soon and merge this :)