Refresh and restructure the Ember CLI Guides

[jenweber]

Rendered

[Gaurav0]

Hey, Jen! This is an awesome start. I really like that you will call for contributors.

The Ember CLI is quite stable, so it is expected that content churn will be low as new releases come out. Members of both the Learning Core Team and Ember CLI Core team will have merge access.

I'm afraid this is not going to be true going forward. Particularly large changes will be required around the packager changes, tree shaking, and module unification. We should discuss how to manage these.

[ynotdraw]

This is awesome, Jen! Having the ember-cli guides be an Ember app like the main Ember guides is a great idea. From a contributor perspective, it'll be great to hop into any of these guides-apps and feel comfortable. Not only that, but the UX consistencies between the different guides is great (imo).

I like how the table of contents flows - adding a tutorial for creating addons will be very helpful, great idea. What you have provided via the Netlify link is fantastic - I like how the tutorial not only walks them through creating their own addon, but also provides links to documentation (pointing towards ember-cli-addon-docs). I wonder if it'd be helpful for more junior folks to have a section on deployment strategies for addons (npm, artifactory, etc.)?

[jenweber]

@Gaurav0 thanks! You raise a good point about those two features. Particularly the file layout of module unification will affect some parts of these guides. I wonder if we should have a section that is dedicated to deprecated features/structures. So, as new things land, we keep the guides up to date, but provide links to content about older behavior. What do you think?

@ynotdraw I like the idea of providing some deployment info. At the very least, we could possibly provide some pointers/links to outside resources. I imagined these guides as having more external links. We have a link checker in the works, so if any links become invalid, we can catch it in CI.

[karlbecker]

Thanks for the writeup, Jen! Easy to follow and thoughtful suggestions. Here's the smattering of thoughts I had:

Ember's public sites are being migrated from Ruby apps to Ember apps

Wow - glad this is being done, I didn't realize they weren't on Ember!

a greenfield approach is more time efficient and will lead to a better learning experience

Rewriting vs refactoring is always a tough call, though I think I understand why greenfield is being proposed here. Here's an SO answer in case anyone wants to ponder about it more, as well as a link to Joel's article on rewrite. But certainly understand why it looks like a greenfield approach is best!

After this RFC is accepted, a call for contributors will be made.

Seconding what @Gaurav0 mentioned - this sounds great! Will those responsibilities be delegated out in, say, Slack, or on GitHub somehow?

From the TOC section:

Why is the CLI needed

Is this a question that comes up much? This strikes me as a question someone coming from older, pre-ember-cli versions might ask, but since many javascript-based apps have some kind of build pipeline these days, I wonder if selling the developer on this is important. Just a thought to potentially save a little effort 😊

[sandstrom]

@jenweber Overall very positive! 👍

From reading the RFC it isn't clear to me if the idea is to keep the old website (ember-cli.com) around, or deprecate/remove it. I think you should move everything over to *.emberjs.com and turn the old site into 302s or use a deprecation banner.

[jenweber]

Ok, I have made a series of changes! Everyone please have a look and let me know if I have addressed your comments, or you have further questions/edits to suggest. Thank you! 😄

1. Following discussion with the learning team, content will ultimately be hosted at an emberjs.com subdomain, as cli.emberjs.com. This is the direction we are headed for all our site apps.
2. The url will contain /release/ in the path. There are 2 reasons for this - one, it allows for future growth if we want to do versioning, and two, it means we can use the same docs tooling that powers the regular (versioned) Ember guides.
3. I added more to the "Maintaining" section to account for module unification. @Gaurav0 is totally correct that things will change. (Any more thoughts on it after these changes, Gaurav?)
4. I added more to the "Call to action" plan, cc @karlbecker
5. I added deployment as a topic, cc @ynotdraw
6. The old site will redirect to the new content/site upon reaching feature parity. I would not be surprised if that takes a year. This will take some fancy footwork with URL handling so that we redirect to real content, but I think we can do it. Is this technically feasible, @mansona? (cc @sandstrom)

[jenweber]

@locks what do I need to do for this to be eligible for final comment period?

[kellyselden]

This is well over-due for FCP. The docs site is ready for change! Starting the timer.

[MichalBryxi]

The RFC mentions a netlify link, but it seems like the app is not working. Just renders "Not found".

[jenweber]

@MichalBryxi good catch, thanks. I removed the link altogether, and directed people to go to the repos, since the most up to date link will always be there. Here's the latest link in case you want to take a look! https://ember-cli-guides.netlify.com/release/ This link will also be temporary.

[jenweber]

@kellyselden ready to merge?

[jenweber]

I think this RFC is ready to merge! Is there anything else I need to do?

[rwjblue]

Thank you!