[WIP] marketing #474
[WIP] marketing #474
Conversation
ashleygwilliams
changed the title
|
|
|
The other use case that stood out to me is |
|
@grovesNL i think the standlone ( |
ashleygwilliams
force-pushed
the
marketing
branch
from
f4ceafb to
8b2bf49
Compare
|
|
ashleygwilliams
force-pushed
the
marketing
branch
from
0f47f45 to
fb9a1cb
Compare
| package in workflows that you already use, such as [webpack] or [greenkeeper]. | ||
| browser or with Node.js. `wasm-pack` helps you build rust-generated | ||
| WebAssembly packages that you could publish to the npm registry, or otherwise use | ||
| alongside any javascript packages in workflows that you already use, such as [webpack] |
There was a problem hiding this comment.
Maybe write JavaScript instead of javascript to be consistent?
There was a problem hiding this comment.
good catch! i was trying but looks like i missed this one- whoops!
| <div class="four columns"> | ||
| <header> | ||
| <img src="./public/img/npm-packages.png" alt="npm packages" /> | ||
| <h4>npm Packages for the Broswer and Node.js</h4> |
There was a problem hiding this comment.
Typo, Broswer -> Browser. Also, should it be capitalized?
There was a problem hiding this comment.
good catch! and no probably not- will fix
| <p> | ||
| Leverage the power and breadth of the Rust ecosystem by compiling | ||
| and publishing packages from <a href="https://crates.io">crates.io</a> | ||
| as WebAssembly packages to the <a href="https://npmjs.com">npm Registry</a> |
There was a problem hiding this comment.
Is the npm registry the only registry that's supported? Or is it possible to use your own registry?
There was a problem hiding this comment.
other registries would totally work, though it uses npm under the hood so it would need to be an "npm-like"/"npm-compatible" registry - not sure if that's too wordy? any thoughts?
There was a problem hiding this comment.
That's great. Not sure if it's worth mentioning? But if it is, then I think "npm-compatible" sounds best and I don't think it's too wordy really.
There was a problem hiding this comment.
ok! i'll update it to say that :)
Co-authored-by: Patrick McCarver <[email protected]>
…the existing template deep dive
ashleygwilliams
force-pushed
the
marketing
branch
from
78a3818 to
4a7cd6a
Compare
ashleygwilliams
force-pushed
the
marketing
branch
from
fa2c17a to
78860b9
Compare
|
Looking this over, I'm personally sort of a bit confused to the long-term prospects of these changes. We've historically had a good deal of confusion about what's documented where and the projects under the Rust and WebAssembly Working Group umbrella feeling somewhat disparate, especially the flagship projects like wasm-bindgen and wasm-pack. We've been trying to fix that with PRs like rustwasm/rustwasm.github.io#41 as well as improved cross-linking of documentation in the game of life, wasm-bindgen, and wasm-pack books. This looks to be a new landing page for wasm-pack, though, which seems like it might add to the confusion? (for example where do new users start? Should we point them here or at the game of life tutorial?) We probably don't want to have three different landing pages (one for the working group as a whole, one for wasm-bindgen, and one for wasm-pack), but rather just one that serves all those purposes. I don't think that this PR as-is would serve well as a landing page for all these projects, and I don't think we want to develop a separate landing page for wasm-pack and the working group. (I can go into more detail about what I think is missing for a landing page for the whole working group, but it seems like this wasn't designed with that in mind so might not be too relevant). In terms of the new book content, I think that we'll want to be sure to include references to the Game of Life tutorial as well as the examples and documentation in the wasm-bindgen book/reference. Currently I don't find too many of either but if this is intended to be an initial landing page for lots of new users I think they'll want to be able to jump to that content as well. I'm personally all for incremental improvement, but I fear that we may find ourselves stuck if we merge this almost as-is for quite some time before we see the next incremental improvement. I would prefer to avoid a situation where we, for a few months, have a separate landing page for wasm-pack which suffers from a number of the drawbacks I mentioned above. |
|
so the primary goal of a landing page like this is to provide an entry point to new users. it has calls to action based on the "targets" that we have, and it links to quickstart tutorials that funnel folks into their choice of workflow. from there it funnels folks to the GoL tutorial which is a "deeper dive" and will teach them about all the components they can use in whatever workflow, with whatever target they want to use. the GoL tutorial is in depth and isn't a good candidate to show off the different templates/targets/workflows. a hello world is tho! and that is why we've been working on quickstart gudies for the templates. it's true this was designed for wasm-pack specifically, but i think that that would also make a reasonable first attempt at a landing page for everyone because wasm-pack workflows are the first thing that end users touch. from there - they go to wasm-bindgen and then twiggy and the other tools. this page was motivated by the fact that a lot of people are unclear on all the targets that are available and supported. this makes them first class citizens and puts them upfront where i think they belong. can you say more about how this will cause debt if landed in it's current state (or a more completed/cleaned up state?) fwiw wasm-pack already has a landing page, so this certainly doesn't add one. but i do think it makes it more useful. |
|
If the goal here is to provide an entry point to new users, I feel like that hasn't really been discussed concretely with the working group much. I was under the impression that the game of life was our introductory material, and updated wasm-bindgen's docs to indicate that. I would personally disagree that the entry point for all new users should live in this repository, but rather the game of life tutorial should continue to be the entry point for new users. I think the content here is fine for new users, but it appears misleading being in the wasm-pack repository. For example Cargo doesn't host the documentation for an introduction to all new Rust users! I think it's more appropriate to have a dedicated house for new documentation, and being adjacent to the "meat" of an introduction (the technical bits like the Game of Life) seems more appropriate.
I believe our goal as a working group should be to have one entry point of documentation and a unified documentation story across the Game of Life tutorial, wasm-bindgen, and wasm-pack. There should be a clearly agreed up on entry point and the documentation should all link to one another where appropriate. This PR is a step backwards from that by introducing a second new landing page, which would be an immediate source of debt we need to pay down at some point in the future. It's hard for me to comment on a completed/cleaned up state though because I don't know what you have in mind for more content. I would personally prefer, however, that the book in this repository is a reference/house for examples for wasm-pack, but the intro-style docs all live in the rustwasm/book repository.
Yes, and I would consider this current technical debt we haven't currently paid down, but one we shouldn't make worse. I don't disagree that this makes the landing page more useful, but I think this is a step enough in the wrong direction in terms of a technical debt side that the incremental improvement doesn't outweight it. |
|
so, i am personally a little bit frustrated because i did bring this PR and work up in multiple working group meetings- and it was well received. so much so that i asked @DebugSteven in the meeting to make a quickstart guide for one of the calls to action which they did and merged into this PR. Sven spent a fair amount of time with J reviewing the guide. many active folks in the working group were aware of this work. as i mentioned in the last meeting, i agree that we should have this live somewhere else and be part of a more cohesive landing page. i have mentioned this in every working group meeting in which i have discussed it. as also mentioned in meetings previously, this was a spike on the wasm-pack repo to experiment with some ideas and try things out to eventually move into the primary site. i would have preferred that this discussion happen closer to when this PR was opened or in the discussion on the original issue, but i understand that it's often hard to keep up with things in a timely manner when there is so much going on. for the release today, i would like to merge this because i would like to get @DebugSteven's work out and i think that a quickstart guide for the webpack template will be very useful for folks. however because the websites are NOT tied to releases, i can work with you, @alexcrichton and @fitzgen, to get the website information sorted, post release. i agree that i do not want to have multiple confusing landing pages. i will file an issue on this repo to track that effort. in the future if you believe there is technical debt in this repo that doesn't have an issue- please file it so i can take action! i was unaware you felt so strongly about this and i would like to take the action required to remedy the situation. |
|
I had not personally at least taken a look at this because I had no idea it was so close to completion. I agree I should have taken a look at this sooner, and I'm sorry I didn't have a chance to do so. This honestly, however, feels like a "pot calling the kettle black" situation commenting about the timeliness of feedback... In any case I personally still feel pretty strongly that we should not merge this as is. It does, in my opinion, create multiple confusing landing pages. We've been working to avoid that, and this seems like a step backwards from that. As I said earlier I'm all for incremental improvement, but if the incremental improvements are spread so far apart they don't really feel incremental any more. I think as-is the PR is still missing enough content (aka has a few blank pages) that it may not want to make a release if it's happening today. Are you planning in filling that out though today? I think when filled out and finished the new book content is good to go at any time (although I would like to review it as well). Could the new documentation in the book perhaps be decoupled from the new landing page? I don't want to block any work unnecessarily, and the improved documentation for various modes shouldn't be held up while the best landing page is figured out. |
|
my goal is to flesh this out and finish it for the release. functionally, this PR adds 3 calls to action to the landing page that already exists to highlight new documentation. i am really struggling to understand why this "incremental" change is so damaging. i think if this documentation were live for a few days and early next week we consolidated into a new landing page for the group that would be fine. i think that would be more valuable that me trashing the work and spending time to sort through the commits to separate the book PRs from the site PRs. i have emailed you and @fitzgen to see if we can have an in voice convo about this since it seems that that may be a better venue than comments on this PR currently. |
|
I've seen the email, yes, but I think it's also worthwhile clarifying thinking here where it's not private discussion. In spirit incremental improvements are find and I'm all for landing incremental work and continuing to improve. Experience with wasm-pack, however, shows that incremental improvements take a very long time to land and are far between. For example releases have been spaced very far apart and have frequently missed expected dates. This means that, because the rustwasm.github.io page shows published documentation, this new landing page runs a risk of being presented for months to come. I don't personally think incremental change, or even this, is damaging. Having the incremental changes spaced so far apart is the damaging part because it means we can't iterate. I'm also curious about your feedback on some of the technical points I brought up above about the content of the PR. While the process of merging this and an incremental strategy is part of my feedback, I also don't think that the actual content is good to go (blank pages, missing links, no mention of wasm-bindgen/game of life on the front page, etc). It seems like you're planning to make changes to this PR today before merging, but given the importance of introductory documentation I'd like to have time to review it before we publish it. |
|
@alexcrichton i think there may be a fundamental misunderstanding of this PR and i have not spoken specifically enough and i apologize for causing that confusion. the motivation for this PR is largely a result of the mdbook interface. when landing on the wasm-pack docs, the only "direction" that users are generally given is the table of contents. while this works for some, i personally think there is benefit in providing a different interface - the one that the landing page is using - to help funnel folks to the right docs more quickly and to surface parts of the doc that might be unhelpfully obscured by a table of contents view. this page is to serve as a landing page into the wasm-pack docs. i mentioned in the last meeting that it may be helpful to take some of this content and make it part of the larger revamp of the working group landing page because i think the calls to action help navigate folks to where they can get started quickly instead of multiple books and tables of contents that can be overwhelming. the missing pages in the PR are the pages that would give a quickstart for using the --no-modules target, the other docs are a PR from J about using the webpack template, and the existing quick start guide for wasm pack that uses the default target. i was holding off on the --no-modules guide as i suspected that the web target would land and we'd want to have the quickstart guide be for that instead. the quickstart guides arent really new content, they are simply how to use wasm-pack for different targets and pointing to the templates. to land this i would be happy to simply remove the CTA for nomodules and land that after the release. i agree that the end of each quick start guide should funnel folks to the game of life tutorial- and i can make those edits! it's a good catch to note that they do not currently do that. i would also be happy to like to the game of life tutorial from the main page. i hadn't because this was really just meant to be a landing page for the wasm-pack docs, but i think it could be a great addition. when viewed as a page to guide folks into the wasm-pack docs, does this seem less objectionable? |
|
From reading @alexcrichton's comments about this PR, I wanted to make sure the goal of this PR was clear.
I agree that's the case. To follow with this analogy, this PR in my opinion is meant to be like the cargo book. You could think of the end goal of this PR as being as in-depth documentation on how to use the wasm-pack tool with more detail on the particular templates. I personally think that would be helpful to have because when I wrote the 1st guide I learned a lot. If I end up writing some of the others I think I would learn a lot more about those templates & why someone might want to use them as well. I think the "landing page" in this case is a fancier looking introduction page of a book. At least, that's how I was thinking about this. I'd also like to mention a little about the tone of this most recent conversation. My perception has been that there has been some miscommunication & different priorities leading to more aggressive sounding back & forth on this issue. I might be wrong that's what lead to this particular scuffle. Would asking clarifying questions & assuming the best intent from each other prevented it? I believe that you both want what's best for this project & I think we can all accomplish more as a team if we build each other up. |
❤️ cosigned, you're all smart folks that I admire a ton! Hate to see friction, and hope we can find a solution together. Thanks for voicing this @DebugSteven |
|
Ok so Alex, Ashley, and I just had meeting to discuss the friction that's been coming up recently in this thread and others. We very explicitly did not talk about decisions that affect the working group or the content of this PR or any other, because we all strongly believe that those discussions need to happen in a public forum that any contributor can participate in. We only discussed our working relationships and things we can do to improve them. I think we came to a better understanding with each other and I'm hopeful that things should improve going forward. Just leaving this comment to let everyone know that we've hit the reset button, and that I think the technical discussion in this thread can continue from here without cycling back over the meta discussion. |
|
Thanks for clarifying @ashleygwilliams and I think that this PR definitely makes sense as a guide into wasm-pack docs (and definitely agreed that no mdbook-generated page really lends itself well to a landing page). I think though that this page is almost a really good entry point for all of Rust and WebAssembly rather than just wasm-pack, and perhaps we can smith it a bit to get there? Concretely I might propose:
|
|
Historically, having disparate docs and home pages has been confusing for newcomers, and we've been making an effort to unify them, eg with the recent bookshelf work. Therefore, I agree that we should use this (sweet!) landing page as our working group's landing page, since it is an improvement over what we have and continues the unification effort. |
|
I should also mention that if @ashleygwilliams you're busy doing the release I don't mind doing some legwork to get this integrated into the https://rustwasm.github.io/ page |
|
thanks for the offer @alexcrichton :) but i should be able to handle it today! the changelog is basically done, i just need to sort #547 and then i can take on this. |
fixes #466