Restructuring the Guides Table of Contents

[jenweber]

Rendered

[lifeart]

Is it possible to add kinda ember-auto-import into "Working with JavaScript", to get users easy way to include any npm installed module?

In components section it will be nice to have different components types overview. (https://www.chriskrycho.com/2018/higher-order-components-in-emberjs.html, https://medium.com/macsour/components-patterns-in-ember-js-5e6fc6eea28f) (updated: looks like it's already covered)

Also, we should point to end-users template-only components it's a kinda component without owned context, not just template.

Should we add any CSS technics/usage section?

[jenweber]

@lifeart good idea, I agree that we should definitely tell devs about it in "Working with JavaScript." It's covered in Addons & Dependencies, and we can link to it. I also agree that we should have something about CSS. This RFC aims to do the bare minimum to rearrange what we have and prepare for Octane, so CSS/specifics of subtopics is somewhat out of scope.

As we consider the Table of Contents, it's likely that there will be many excellent "out of scope" ideas/reflections that can be turned into action items, so I just created a Gist here that anyone can comment on, and I'll add to it as we go along: Community Ideas for the Ember.js Guides

[pzuraq]

This RFC is absolutely excellent! I especially like the clear and concise rules for defining the "Fundamentals" and "Leveling Up" sections, I think that they will be great guides for reducing bikeshedding in the future about where something should go.

Overall I'm very 👍 on this RFC, I like the groupings, and I think it also makes excellent use of our existing content and minimizes the changes that will be required for Octane. One thing that has been concerning for folks reviewing the various RFCs (Glimmer Components, Modifiers, Tracked Props, etc.) is just how much of the guides will need to change, and I think this does an excellent job of outlining and calling out those things specifically.

The one thing I might add is a section on Template-Only Components under Components (cc @mike-north on that) but I think based on the language of the RFC, the exact content for each section is not what is being proposed, so much as the overall groupings and the rules for those groupings. That means we would have plenty of flexibility to change those individual subsections as we begin the refactors, if we realize that we needed another section or a section was actually not needed. Correct me if I'm wrong there, I just don't want to start bikeshedding too much about the details if that's not the focus here!

[jenweber]

@pzuraq you are right that the focus is on the "rules" and high level topics. That said, for the "Creating a component" section, it has a callout to "Types of Components" in order to cover that. I have also noted it in the Gist! Thanks!

[CodingItWrong]

Tiny bit of feedback; I may have more later. I feel like other frameworks refer to "dev tools" rather than debugging, so that may be a better option for the Table of Contents item. It might not be as good for those who don't know frontend dev, though.

[NullVoxPopuli]

does this one already exist?
would this section also explain the why about templates? idk if we want to cross into defense territory in the guides, but I've had a good number of conversations on reddit about the advantages of templates over JSX.
Also, not sure if it's a battle worth having.
idk. 🤷‍♂️

[jenweber]

Template Syntax currently exists as a subsampling of Templates. It would need a new intro on the first topic.

I can imagine that it would include a little bit of why. Do you have any material we could draw from? A good followup here would be to create an issue in the Guides. Nothing stops us from adding a little bit of "why" in today.

[NullVoxPopuli]

I'm a fan of this, components can do a lot, but all that extra stuff would go in "Leveling Up", which I think is good. starting out, people don't need to manage remote data / queries in their components, but that would be a good topic for a standalone guide rather than in the intro guides (for example). 👍

[jenweber]

Yeah I'm a bit on the fence about it. I would like to hear more feedback from a couple other people, especially people who are new-ish to Ember.

[NullVoxPopuli]

What does the community think of this structure? How can it be improved?

I think it's really good as proposed.

Is it good for new learners? Is it good for existing users?

oh yeah, for both. My only concern is for people coming from other ecosystems, but maybe we can do separate sections on that in the future. I kinda started ember & react blogs at my company, but haven't had time to keep writing them -- I could contribute / adapt those for the ember guides if those are desired.

What possible pain points does the community see?

Really if someone is only familiar with React:
Why templates? why not jsx? why no functional components? why objects/classes?

Are there any areas missing from the Table of Contents?

Maybe some performance investigation tips? or how to create meaningful benchmarks? maybe those'd be sections on debugging? idk

What do people think of removing the “Ember Object Model” section?

Looking at the existing docs, there is probably a lot that can be removed when we switch to ES classes / tracked / etc. I don't know if this'd be a good place to show when things are OO and when things are/can be FP, but I think newer devs may be less familiar with different paradigms.

Are the goals of the Ember Data and Ember Inspector teams supported by this new layout?

🤷‍♂️ :)

Overall, very 👍 nice work! 🍾 🎉

[pzuraq]

@NullVoxPopuli

why no functional components?

Worth noting, I think template-only components are our equivalent of functional components, since they can't have state, and we should call this out in that section.

[dbendaou]

I like the idea of the Routing group since router, route files and controller files are very related and it's not quite evident in the actual guide.

This new table of contents may help a lot to decrease the slope of ember learning curve. 👏

[ghost]

My high level and brief feedback:
I am heartily in favor of restructuring the guides as proposed here. I think it fits well with the broader JavaScript community and thus would leverage developer's existing knowledge.

[Gaurav0]

How are we going to teach both classic and glimmer components? I would like to propose all content specifically pertaining to classic components be moved to Leveling Up following the Octane release.

[gossi]

I think the outline for this section needs to be revisted again in terms of general patterns, e.g. adding actions, passing arguments or state management with computeds/tracked vs. component-type related topics. There is ember-components, sparkles/glimmer components, hooked components, template only components ... and all of them have different APIs (template only has none! :D) but lifecycle hooks are different for those types of components. The guides shall not spread the idea of ambiguity amongst them.

[jenweber]

@gossi good point about separate lifecycle hooks. I would like to break down the subtopic names into "things people want to do" as opposed to syntax-specific implementations. Do you think that's realistic?

How's this?

- Creating a component (describes all component types and why you would choose each one)
- Displaying data in a Template
- Adding actions
- Nesting components (includes suggestions of when to break things into components)
- Passing arguments
- Component state management (mostly just linking to Services and State Management top level topic)
- Working with arrays of data
- Lifecycle hooks (for each type of component)

If you would use different categories, can you list them?

[gossi]

Technically it would make sense to start with embers component manager and explain there can be different types of components ... and this will be the point where the guides will state ember as suuuper difficult. Not a good way to get learners onboarded but technically not wrong :D

Instead, what may be more helpful to pick a little example that states:

• how to create a component
• how attributes and arguments work (and how to handle defaults for @arguments - this WILL come up)
• how to bring properties from component to template (in combination with state managemet)
• how modifiers interact with components at the example of action
• ..... where we'll come to lifecycle hooks stating different types of components

From your list "Displaying data in a Template" and "Working with arrays of data" seems like repetitive (only given the headlines). Nesting components is an advanced topic, which would better interact with given patterns (not only for ember) that exist for components and how to apply them with ember, which opens another section for the guides (what I just send you over at discord).

The list I outlined might still be technically driven but I'm quite happy with my grouping now make it approachable to beginners =)

[MelSumner]

@jenweber can we add an accessibility section? I know it's not Ember-specific but it is something we should make sure every Ember developer is aware of.

I'll own making sure the content is created, and I think it's important for our guides to address.

[jenweber]

@MelSumner This PR is mostly about the bare minimum to do Octane, but since Accessibility is such a glaring omission in the Guides, I'll include it. It is one brand new topic that I think merits being added!

[jenweber]

I have made some small changes to this RFC thanks to feedback by @mike-north!

1. Reunite Template syntax and helpers. Custom helpers are much more powerful than I realized for showing off the capabilities of templates and unit tests, in a way that is welcoming to people coming in from other frameworks and total beginners
2. Add a section on who our audience is

Then from the Learning team:

1. Upgrading explicitly includes editions conversion guides.

[jenweber]

@lupestro thanks for the input! Initially I had called it Debugging, but based on feedback from others, changed it to Developer Tools because it was suggested as a broader term.

I think I would like the Ember Inspector team to weigh in on what to name the section that would help people discover Inspector. It's the most powerful tool we have. @rwwagner90 or others, any thoughts?

[jenweber]

The Learning Core team has decided to move this to FCP, "Final Comment Period." To learn more about what FCP means, see the RFC README. In short, more comments are welcome but the days are numbered.

Thanks to everyone has participated so far, both in this PR and chat!

[RobbieTheWagner]

@jenweber React has a Tools section, and a subsection called Debugging under it. https://reactjs.org/community/debugging-tools.html

Vue calls it Tooling with a Devtools section under that. I think the common theme is have a section for tools, then have something related to Debugging/DevTools under that.

[chrism]

I've only just seen this RFC, but have to say it looks great to me.

I do have one comment, but it's more of an observation on one particular use case with the current guides that I‘d love to use this as an opportunity to mention.

Often I find myself wanting to refer to documentation on a specific 'new feature' announced in a recent version of Ember. The blog posts include very clear documentation on how to use it.

For example, to use optional features.

Currently the quickest way I can access that, unless I've missed something obvious, is to go to the blog section and click through each release blog post individually until I find the release where it was added (in this case back to 3.1). There's an extra step to filter to just releases too which helps a bit.

All in all I feel like it would be great if these new features got folded into the guides, perhaps as an extra section in the 'upgrading' section — even just features and links, I'm not sure about the implementation but just think this great content should be floated higher and more easily accessible if possible.

[yarigpopov]

@jenweber please think about this order in Fundamentals

• Components
  My guess is that most of people who will read the guides will be familiar with React and I suggest to start with this section cause it would be most familiar section for them.

• Working with JavaScript / Templates
  I don't have strong opinion what should go first, it should depend on how Components will be written and what will be the bridge. One thing I really would appreciate to see in Template section is that they automatically resolve promise-values. When I wrote a React app some time ago I was stunned not to have it there.

• State management (aka computed properties)
  Here maybe we can mention some similarities with Vue.js. In case the guides will be read by those who tried Vue.

• Routing (includes Routes, Router, and Controllers)
  Here would be nice to explain semilarities with React router (since it was a port from the Ember one). And in the end we can make a bridge to services (since Router is a service)

• Services

[mike-north]

I love that you're thinking about optimizations that could be made around visitors who have context from other technologies, but there are a lot of different places people could be coming from.

For example, an early version of React Router credited Ember's router as a source of inspiration, but the current version is very different. Even for just this one library, which versions(s) should we assume?

Kicking off right into components is an interesting idea! The main difference between React's component model and Ember/Vue/Angular is the use of declarative templates instead of a Component#render function -- wouldn't this suggest that templates should be introduced first?

These points you're focusing on are valuable, but really tough to get right in a "throughout the guides" kind of way. Maybe we could channel these ideas into a new section like "...So you're coming from React..." that aims to establish a bridge between a reader's understanding in one world to the ember world

[yarigpopov]

wouldn't this suggest that templates should be introduced first?

I also thought about this. And came to the conclusion that better to start with a similarity before moving to differences.
I heard many React guys saying that they don't like templates and "JSX is just JS". Therefore It would be nice to have a section that will explain the rationale of using templates. That it is on purpose and gives advantages. Not just historically. First sell templates as concept to people before explaining it.

which versions(s) should we assume?

Great that somebody more familiar with React ecosystem came in. I think we should aim on the current version. Are there still similarities?

So you're coming from React

I think this is wonderful idea! Maybe a bit rephrase it to "So, you're familiar with React", something less offensive (or it is only me who feels bit offensiveness in you variant?)

[mike-north]

Great that somebody more familiar with React ecosystem came in. I think we should aim on the current version. Are there still similarities?

Nope, and this is part of what might make the approach of relating to other libraries challenging. They're all moving targets.

[yarigpopov]

Very valuable point. And just in the right place.

I would like to see here detailed explanation about ember's folder structure and how this convention enables reusability of addons.

[yarigpopov]

Also, since we discuss here folder structure, would be nice to mention here CLI which takes care about boilercode, naming and folders.

[MelSumner]

@chilicoder we could probably add a callout that links to the CLI guide. We purposefully designed this component for just this sort of use case. 👍

[MelSumner]

@jenweber -

We propose that the Guides should focus on the following audience - newcomers who have done the tutorial, and want to build real apps. It will show the "happy path" and how the parts of Ember interact to form good, useful patterns, in a way that would be out of scope for an API documentation block.

Since this is the audience that the guides already focus on, should we phrase this to reflect that? Maybe "We propose that the Guides should continue to focus on the following audience"?

Maybe not necessary, but food for thought.

Excellent work on this RFC!

[jenweber]

Hello everyone! Thank you so much for all your thoughtful comments and suggestions. The Learning Team has reached consensus to merge this RFC. I'm excited that we have this opportunity to improve the learning story, alongside the improvements that come with Octane.

Considering this is just the "MVP" plan, the future is looking good :) We welcome your continued feedback and ideas along the way.