guides icon indicating copy to clipboard operation
guides copied to clipboard

Write some of the sentences on the Core Concepts page

Open Fryie opened this issue 9 years ago • 1 comments

https://guides.emberjs.com/v2.4.0/getting-started/core-concepts/

I'm trying to work on the translations and there were a couple of things that tripped me up a bit, so I want to just give my take on this.

Templates can also display properties provided to them from their context, which is either a component or a route (technically, a controller presents the model from the route to the template, but this is rarely used in modern Ember apps and will be deprecated soon)

That sentence in the parens is really long, and if you translate it into German it just gets longer (that's just how German works :P). Additionally, there's not really a word for "deprecated" and I'd have to more verbosely explain it (i.e. something like "this is going away in a future version" or something). Also, I think for an introduction to the concepts it's just a bit too technical maybe. Furthermore I'm just not sure what it means to say that "technically there is a controller, but it is not used". I don't want to step on anyone's toes but I'm kinda really having a hard time with that half-sentence. If you really have to talk about controllers on this page, maybe it should be a separate session (even if that session basically only says "controllers are there for technical and legacy reasons and should not be explicitly used for new code" or something to that effect).

Here, {{name}} is a property provided by the template's context.

Besides properties, double curly braces ({{}}) may also contain helpers and components, which we'll discuss later.

Maybe, for the sake of consistency, we might want to refer to name as the property, instead of {{name}}, especially since the next sentence basically says that curly braces contain properties

While templates describe how a user interface looks, components control how the user interface behaves.

Components consist of two parts: a template written in Handlebars, and a source file written in JavaScript that defines the component's behavior.

To my mind, that's contradictory. First we establish an opposition between templates and components, but then we say that a component also has a template file. I'm not sure how to resolve this, but it sounds less than optimal to me. This is probably due to the fact that "component" can both mean the JS + template combination, but it can also refer only to the JS file. The first sentence kind of uses that latter meaning of "component", while in the second sentence we use the first meaning. To a novice, I don't think this is obvious. Again, I'm not sure what else to suggest. Maybe something like "Sometimes (often?) you want to add behaviour to parts of your UI. To that effect you can use components. Components consist of two parts ..."?

I realize that some of this is due to the limbo that Ember is currently in, moving away from controllers, so I realise that it's hard to come up with good descriptions for the concepts. The guides have improved substantially since I started with Ember, so thumbs up to anyone involved. :+1:

Fryie avatar Mar 01 '16 13:03 Fryie

@rtablada Would you have a chance to take a look at smoothing out some of these wrinkles?

acorncom avatar Mar 10 '16 19:03 acorncom