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

Determine a rule-of-thumb for what content should be moved from the Ember Guides #168

Open
jenweber opened this issue Apr 9, 2020 · 8 comments

Comments

@jenweber
Copy link
Contributor

jenweber commented Apr 9, 2020

@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?

@mehulkar
Copy link
Contributor

mehulkar commented Apr 9, 2020

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 index.js hooks). So it's not entirely clear where to document them or if to split up the documentation. Or to just reference the build time section from the Components guide, for example.


  1. this is one of the reasons for Ember CLI build pipeline emberjs/rfcs#578, actually. I want to decouple addons from the recommended solution for build time code, so that it's easier to teach them.

@jenweber
Copy link
Contributor Author

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.

@Gaurav0
Copy link
Contributor

Gaurav0 commented Apr 24, 2020

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.

@locks
Copy link
Contributor

locks commented Apr 24, 2020

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 ember new my-project.
I think an example we brought up as fuzzy is contentFor, since to do something with it you need at least an in-repo addon, but it seems unlikely to be an 80% case.

@locks
Copy link
Contributor

locks commented Apr 24, 2020

And as always, think of the guides as actual books x)

@maxwondercorn
Copy link
Contributor

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.

@jenweber
Copy link
Contributor Author

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 ember new experience.

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!

@jenweber
Copy link
Contributor Author

Ember Learning Team handbook PR is here: ember-learn/handbook#36

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

No branches or pull requests

5 participants