-
Notifications
You must be signed in to change notification settings - Fork 53
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
feat: add page to hold additional references #178
Conversation
There was a problem hiding this 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
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 |
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. |
I would note that all the links in that reference are mentioned IIRC in the pages prior -- but I certainly agree with this:
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! |
@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>
23dde6d
to
b7b9bd8
Compare
Signed-off-by: Victor Adossi <vadossi@cosmonic.com>
Hey @itowlson @kate-goldenring any more feedback here? |
There was a problem hiding this 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!
Bump on this -- @kate-goldenring what do you think? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
This PR adds a basic page for holding/accumulating additional references that help understand the component model
Resolves #12