Octane Quickstart guide review

[lisaychuang]

Hi everyone,

I've taken a look at the Octane guide preview, and here are my thoughts & suggestions!

"Quick Start", url: "quick-start"

• https://github.com/ember-learn/guides-source/blame/octane/guides/release/getting-started/quick-start.md#L121

You should see the <h2> you put in the scientists.hbs template, right below the <h1> from our application.hbs template.

In the paragraph after the code example for app/templates/scientists.hbs, it may be helpful to point out that the <h2> is rendered because /scientists is a nested route, so the code in the corresponding template will be rendered in place of the {{outlet}} in application.hbs, and link to the API doc on outlet for further info.

• https://github.com/ember-learn/guides-source/blame/octane/guides/release/getting-started/quick-start.md#L129

We'll take the code created for us by the generator and add a model() method to the Route

In app/routes/scientists.js, the code that was auto-generated in my file shows:

import Route from '@ember/routing/route';

  export default Route.extend({
});

Whereas the code example shown in the guide shows the code below, which has class ScientistsRoute in export default:

import Route from '@ember/routing/route';

export default class ScientistsRoute extends Route {
  model() {
    return ['Marie Curie', 'Mae Jemison', 'Albert Hofmann'];
  }
}

After speaking with @mike-north, looks like the Octane quickstart does not have the reader use -b @ember/octane-app-blueprint at the end of ember new quickstart, so we are now missing blueprint in generators.

Even if we did include the argument, which would have generated a new Octane app, there do not appear to be native class generators for route / controllers etc
It appears when using the octane-app-blueprint code is generated properly

This result in the difference between the code the reader (me) got by following the guide.

• https://github.com/ember-learn/guides-source/blame/octane/guides/release/getting-started/quick-start.md#L251

In this section, I ran the ember generate component people-list command to generate a component. However, when we get to the code example for app/components/people-list.js, the code generated in my file is again different from the code snippet. This is a similar error to the route generator above.

-- FROM THIS POINT ON, I RESTARTED THE TUTORIAL USING THE OCTANE BLUEPRINT --

• https://github.com/ember-learn/guides-source/blame/octane/guides/release/getting-started/quick-start.md#L185

In order for this code to work, it should be @people instead of this.people since the prop is passed in from application.hbs, not component state.

• https://github.com/ember-learn/guides-source/blame/octane/guides/release/getting-started/quick-start.md#L252

It appears that the code example diff is out of sync, as line 2 is added: import { action } from '@ember/object'; and line 5 -8.

---

"Installing Ember", url: "index"

No typos noted / suggestions for

---

"Core Concepts", url: "core-concepts"

• https://github.com/ember-learn/guides-source/blame/octane/guides/release/getting-started/core-concepts.md#L39

Upon reaching this point, the word context is used to describe where a template gets data from (i.e. a component or a route's controller). This seems quite abstract to me, I would have liked to see what this context looks like, and see where this template gets its data from.

Since a code example is provided, perhaps it will be helpful to provide 2 files (with file names) so that it is a clearer example?

Alternatively, there is a section on Understanding a Template's context in the ** "Templating Basics"** section. A link could be added to point readers to skip ahead to this section.

---

"Anatomy of an App", url: "anatomy-of-an-app"

• "Overview", url: "index" (this section is blank)

---

"Templating", url: 'templates'
"Templating Basics", url: "handlebars-basics"

• https://github.com/ember-learn/guides-source/blame/octane/guides/release/templates/handlebars-basics.md#L33

The best way to tell if a template is part of a Route or Component is to look at the file path.

It may be helpful to elaborate on this point, and state where readers can expect to find associated templates in the app structure. Component template files will typically be in app/templates/components, and route templates will typically be in app/templates.

• https://github.com/ember-learn/guides-source/blame/octane/guides/release/templates/handlebars-basics.md#L112

In the other pages of this guide, we will cover the features one at a time.

Suggestion: change to "these features" or "various features"

• https://github.com/ember-learn/guides-source/blame/octane/guides/release/templates/handlebars-basics.md#L113

In general, special Ember functionality will appear inside curly braces, like this: {{example}}. Here are a few examples of Ember Handlebars in action:

Suggestion: Add a sentence on how curly braces {{ }} are a part of Handlebar syntax, or to elaborate on what Ember Handlebars mean.

• https://github.com/ember-learn/guides-source/blame/octane/guides/release/templates/handlebars-basics.md#L174

Lastly, it's important to know that arguments can be passed from one Component to another through templates: (a code example)

To pass in arguments associated with a Route, define the property from within a Controller.

In this paragraph, two concepts are introduced:

1. Passing arguments from one component to another
2. Passing arguments from a controller to a route template

However, it is confusing to read Lastly, it is important... expecting to learn 1 concept. Suggestion to remove the word "lastly" and to include code examples from both concepts.

---

...in progress as I continue to review the guides

[mike-north]

@NullVoxPopuli since you've been the point-person for ember-cli/ember-octane-blueprint, can you comment on what the plan is for native classes and generators?

Looks like creating an app w/ the octane blueprint results in codegen in ES6. Once we update the quickstart to direct users to this blueprint, we should be in better shape.