-
-
Notifications
You must be signed in to change notification settings - Fork 76
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
Determine a rule-of-thumb for what content should be moved from the Ember Guides #168
Comments
The broad separation for me is "things that happen at build time" vs "things that happen in the runtime". There are two overarching themes that I'm seeing from the core team that support this:
Neither of these are a reality (and possibly won't be for a while), but it's conceivable that together, they move the needle forward into thinking of build and runtimes as independent parts of the ecosystem. The tricky part are Addons. Addons are typically used for runtime code (e.g. components), but are also the recommended way to write build time code1 (using
|
I really like this framing. It makes sense to me and it seems like a natural division. I would like to get some feedback on this from @Gaurav0 @maxwondercorn @ember-learn/cli-core-team if y'all have thoughts. We are trying to come up with a rule of thumb that would be used when trying to decide if new content should be added to the Ember Guides or CLI Guides, as well as for migrating content out of the Ember guides and into CLI. |
My thoughts are very much in line with @mehulkar For example, build targets is a build time concern for now and belongs in the cli guides. Another way to consider looking at it is whether the code is running in node.js or running in a browser. Unfortunately, Fastboot makes this a less clear separation, so I think build time or run time is better. |
During a conversation with @mansona I was reminded of an old guideline we also keep in mind, which is that the Guides should cover the default experience of |
And as always, think of the guides as actual books x) |
I just saw this issue. I generally agree that runtime vs build is a good place to draw the line. While I can't think of an example there may be a need to have a "light" introduction in the Ember Guides and the details in the cli guide. Since I can't think of anything this would be pretty rare. I do like the analogy that the guides should read like a book. |
We discussed this in today's learning team meeting and agreed on the rule of thumb that build time info belongs in the CLI guides. This is especially true for new content. On a case by case basis, some build time info may remain in the Ember Guides if it is important for the most common Ember user's experience. If 80% of Ember users need it, it should probably stay in the Ember Guides so that it remains a complete resource for the More info is in the meeting notes here emberjs/core-notes#301 (comment) I will close this Issue once I have added something along these lines to the Ember Learning Team Handbook. Thanks everyone for helping think this through! |
Ember Learning Team handbook PR is here: ember-learn/handbook#36 |
@mehulkar and @Gaurav0 are working on this! This issue just helps to track that they are interested in helping, and also serve as a place where others can add comments.
The question we are trying to answer is, how do we know what content should be moved from ember.js guides to ember-cli guides? More broadly, is there a definition or description that will help us understand whether new content belongs in a certain guide?
The text was updated successfully, but these errors were encountered: