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

[jenweber]

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

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:

• Alternative build tools enabled through Embroider v2 Addon Format (Embroider compatibility) emberjs/rfcs#507
• "Exploding" packages Splitting Ember into packages emberjs/rfcs#284

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 code¹ (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]

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]

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]

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]

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

[maxwondercorn]

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]

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]

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