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

Restructuring the Guides Table of Contents #431

Merged
merged 27 commits into from Feb 16, 2019

Conversation

@jenweber
Copy link
Contributor

jenweber commented Jan 13, 2019

Rendered

@lifeart

This comment has been minimized.

Copy link

lifeart commented Jan 13, 2019

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

This comment has been minimized.

Copy link
Contributor Author

jenweber commented Jan 13, 2019

@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 comment has been minimized.

Copy link
Contributor

pzuraq commented Jan 13, 2019

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

This comment has been minimized.

Copy link
Contributor Author

jenweber commented Jan 13, 2019

@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

This comment has been minimized.

Copy link

CodingItWrong commented Jan 13, 2019

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.


**Fundamentals**

- Template syntax

This comment has been minimized.

@NullVoxPopuli

NullVoxPopuli Jan 14, 2019

Contributor

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. 🤷‍♂️

This comment has been minimized.

@jenweber

jenweber Jan 25, 2019

Author Contributor

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.

Join the Vue.js Community!
Meet the Team

One possible lesson here is that we could split up Components like Vue did with Component Basics and Components In-Depth. Their dedicated section on Computed Properties inspired the inclusion in our new Table of Contents.

This comment has been minimized.

@NullVoxPopuli

NullVoxPopuli Jan 14, 2019

Contributor

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). 👍

This comment has been minimized.

@jenweber

jenweber Jan 25, 2019

Author Contributor

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
Copy link
Contributor

NullVoxPopuli left a comment

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

This comment has been minimized.

Copy link
Contributor

pzuraq commented Jan 14, 2019

@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

This comment has been minimized.

Copy link

dbendaou commented Jan 14, 2019

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. 👏

Show resolved Hide resolved text/0000-guides-restructure.md Outdated
@efx

This comment has been minimized.

Copy link
Contributor

efx commented Jan 14, 2019

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

This comment has been minimized.

Copy link
Contributor

Gaurav0 commented Jan 14, 2019

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.

@jessica-jordan jessica-jordan referenced this pull request Jan 15, 2019

Merged

Ember Times - Issue No. 81 - Jan 18th 2019 #3767

5 of 10 tasks complete
- Passing arguments
- Using computed properties (extremely basic example, link to the Computed Property section)
- Working with arrays of data
- Lifecycle hooks

This comment has been minimized.

@gossi

gossi Jan 16, 2019

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.

This comment has been minimized.

@jenweber

jenweber Jan 25, 2019

Author Contributor

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

This comment has been minimized.

@gossi

gossi Jan 28, 2019

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 =)

Show resolved Hide resolved text/0000-guides-restructure.md Outdated

@locks locks added the T-learning label Jan 19, 2019

@MelSumner

This comment has been minimized.

Copy link
Contributor

MelSumner commented Jan 24, 2019

@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

This comment has been minimized.

Copy link
Contributor Author

jenweber commented Jan 24, 2019

@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 added some commits Jan 31, 2019

@jenweber

This comment has been minimized.

Copy link
Contributor Author

jenweber commented Jan 31, 2019

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

This comment has been minimized.

Copy link
Contributor Author

jenweber commented Jan 31, 2019

@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 added some commits Jan 31, 2019

@jenweber

This comment has been minimized.

Copy link
Contributor Author

jenweber commented Jan 31, 2019

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!

@rwwagner90

This comment has been minimized.

Copy link
Member

rwwagner90 commented Jan 31, 2019

@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

This comment has been minimized.

Copy link

chrism commented Jan 31, 2019

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.


**Fundamentals**

- Templates

This comment has been minimized.

@chilicoder

chilicoder Feb 1, 2019

@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

This comment has been minimized.

@mike-north

mike-north Feb 2, 2019

Contributor

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

This comment has been minimized.

@chilicoder

chilicoder Feb 2, 2019

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

This comment has been minimized.

@mike-north

mike-north Feb 6, 2019

Contributor

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.


- What is Ember?
- Getting Started
- Anatomy of an app (future new content)

This comment has been minimized.

@chilicoder

chilicoder Feb 1, 2019

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.

This comment has been minimized.

@chilicoder

chilicoder Feb 1, 2019

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

This comment has been minimized.

@MelSumner

MelSumner Feb 5, 2019

Contributor

@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

This comment has been minimized.

Copy link
Contributor

MelSumner commented Feb 5, 2019

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

Show resolved Hide resolved text/0431-guides-restructure.md Outdated
Show resolved Hide resolved text/0431-guides-restructure.md Outdated
Show resolved Hide resolved text/0431-guides-restructure.md Outdated
Show resolved Hide resolved text/0431-guides-restructure.md Outdated

locks and others added some commits Feb 16, 2019

Update text/0431-guides-restructure.md
Co-Authored-By: jenweber <jen@biobright.org>
Update text/0431-guides-restructure.md
Co-Authored-By: jenweber <jen@biobright.org>
Update text/0431-guides-restructure.md
Co-Authored-By: jenweber <jen@biobright.org>
Update text/0431-guides-restructure.md
Co-Authored-By: jenweber <jen@biobright.org>
@jenweber

This comment has been minimized.

Copy link
Contributor Author

jenweber commented Feb 16, 2019

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.

@jenweber jenweber merged commit 7d46cfa into emberjs:master Feb 16, 2019

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment