Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add page to hold additional references #178

Conversation

vados-cosmonic
Copy link
Contributor

This PR adds a basic page for holding/accumulating additional references that help understand the component model

Resolves #12

Copy link
Collaborator

@kate-goldenring kate-goldenring left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure it is fully clear what we want the scope of this page to be. IMO i think adding WAC and wkg and tools are in scope. I am happy to add this in and then see how this extends or preemptively discuss

component-model/src/SUMMARY.md Outdated Show resolved Hide resolved
@vados-cosmonic
Copy link
Contributor Author

Yup, that's a great addition -- I was hoping we could add to this references page with whatever links make sense over time! I'll add WAC and wkg as well

@itowlson
Copy link
Collaborator

The listing of individual pages within the WebAssembly/component-model repo feels a bit superfluous, perhaps because as a reader I have no context for the entries. Under what circumstances would I want to read the "component model AST explainer," for example?

Generally I kind of feel these links would be more useful to readers at relevant parts of the text, where they have context and can be introduced with what they add, e.g. "For in-depth information about the binary format of components, see (link to AST explainer)."

That said, there is value for sure in collecting them in one place, like a sort of biblliography. But I would maybe put it at the end of the TOC in a reference section, rather than putting it in the general flow between "understanding" and "using" the component model.

@vados-cosmonic
Copy link
Contributor Author

I would note that all the links in that reference are mentioned IIRC in the pages prior -- but I certainly agree with this:

That said, there is value for sure in collecting them in one place, like a sort of biblliography. But I would maybe put it at the end of the TOC in a reference section, rather than putting it in the general flow between "understanding" and "using" the component model.

What do you think about a "References" Section, and below that a "Useful links"? also @kate-goldenring if you have any opinions here feel free to chime in!

@itowlson
Copy link
Collaborator

@vados-cosmonic That would work for me - thanks!

I would still suggest considering the value of the links within the CM repo. For this book's audience, I feel we should either contextualise these (the actual page names are not very informative to people outside the community of "people working on the component model itself"), or just link to the top level of the CM repo as e.g. "the design and implementation of the component model." I'm really keen not to draw app developers / CM users to these pages with words like "explainer" because they're rather intimidating!

Signed-off-by: Victor Adossi <vadossi@cosmonic.com>
@vados-cosmonic vados-cosmonic force-pushed the feat=add-additional-references-page branch from 23dde6d to b7b9bd8 Compare November 25, 2024 19:26
Signed-off-by: Victor Adossi <vadossi@cosmonic.com>
@vados-cosmonic
Copy link
Contributor Author

Hey @itowlson @kate-goldenring any more feedback here?

Copy link
Collaborator

@itowlson itowlson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good now! Thanks @vados-cosmonic!

@vados-cosmonic
Copy link
Contributor Author

Bump on this -- @kate-goldenring what do you think?

Copy link
Collaborator

@kate-goldenring kate-goldenring left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@kate-goldenring kate-goldenring merged commit 4be8b19 into bytecodealliance:main Jan 20, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Create docs: Additional References
3 participants