Skip to content
This repository has been archived by the owner. It is now read-only.

Improve Guides organization #639

Closed
trek opened this Issue Aug 21, 2015 · 37 comments

Comments

Projects
None yet
@trek
Copy link
Member

trek commented Aug 21, 2015

This reopens discussion around #450 (and supersedes it because it contains a bit more information)

The guides/docs subteam met some time ago and brainstormed a new organization for the guides. This issue tracks those proposed changes and the work to migrate current guides to that. Feedback is very welcome.

High-level Table of Contents

Below is the proposed "top level" headings for a table of contents. The goal of this level of organization is to give readers a better understanding of what topics should be read to understand Ember and what topics can be read later as the need arises. Guide names and order are draft, so don't feel the need to bikeshed them too much.

It is broken into three large sections. A Tutorial Section, A Core Section, and Breakout Section:

  • Tutorial

- Getting Started - Routing - Templates & Components - Services
- Installation - Configuring - Upgrading - Animation - Classes and Objects - Testing - Security - Data Persistence & Ember Data - Inspector - Deploying - Contributing - Glossary ### Tutorial Section

The goal of the tutorial is to replace the old "getting started guide." This tutorial should be followed by anyone entirely new to Ember to see how a basic Ember application is authored including using the cli, planning an app, testing an app, using ember-data, and debugging.

The tutorial, like the old "getting started guide" is written in a series of smaller steps. Each step should introduce (at a very high level) cli/authoring/testing etc concepts needed to complete that step. @locks is working on getting information from @poteto to continue this project.

Core Section

This section covers the core topics needed to develop any Ember Application. Each guide in core section includes any testing/inspector/debugging informaton relevant to that topic.

"Getting Started" provides a high level description of Ember.js, how data flows, a call to action to give the "Tutorial" a try. The goal of this guide is to put your head in the right space for Ember.

"Routing" covers routing, query params, and also includes the "top level controllers" section, since controllers are now essentially for query params, how to communicate from components to routing and from routes to components.

"Components & Helpers" covers the entire view layer: component code, rendering hooks, actions, handlebars and handlebars helpers.

"Services" covers services and other DI related topics.

Breakout Section

The "breakout section" covers useful topics in depth. Many of these topics are covered lightly in both the Tutorial and Core sections and are explored in full depth here. Some examples:

The use of Ember Data occurs throughout the Tutorial and Core sections. The "Ember Data" section here explores the default Ember Data behavior and covers customizing Ember Data to match more API types and covers when and how to use your own request patterns (a task many people still choose to do).

Ember.Object, classes, etc are used in Tutorial and Core sections but explored in depth in their Breakout guide.

Questions:

Are there high level topics that you think are missing? Are there more detailed topics in Ember that you think can fit into this structure?

@stefanpenner

This comment has been minimized.

Copy link
Member

stefanpenner commented Aug 21, 2015

@iagox86 and myself are interested in working on the security document. Our timeline isn't asap, rather in the next few months. So if someone else has a short term plan, our interest should not block it.

@eccegordo

This comment has been minimized.

Copy link

eccegordo commented Aug 21, 2015

Apologies for the verbosity...

But I think there should be a section called
"The Ember Philosophy"
or
"Architecture and best practices"
or
"How Ember opinions are informed"
or
something along these lines

The idea is that this section would be a general, well thought out, well debated, visually rich (diagrams), overview of the ember system from a 10,000 foot view.

So so so much opinion, contention, confusion, and constant questions floating out there.

This section could be the soapbox for the core team and community to really nail down the conceptual parts of this. And a place to point to when the invariable arguments come up, or even honeypot the flame bait that floats out there.

This section would not be heavy in code examples. But rather error on the side of conceptual ideas and the underlying justifications (or debate/controversy). Use this section to really reinforce the terminology and concepts. Use it as a place to explain yourselves and beliefs.

  • Why services...
  • Why routable components vs controllers
  • Why transpilation
  • Why build tools (ember cli)
  • Why a framework
  • Why glimmer and DOM diffing
  • Why Semver
  • How Ember learns from competition
  • What differentiates Ember from other frameworks/tools/philosophies

Other possibilities (albeit potentially more controversial)

  • Why not angular/react/hyped-framework-du-jour
  • Why not controllers
  • Why no more support (deprecation) for specific private/public API (or how I learned to stop worrying and love the removing of cruft)

My thinking is if you have well trafficked segment of the guides dedicated to this topic it will force everyone to distill their ideas down into the crucible of this corner of the guides. More clarity all around, and fuzzy ideas made concrete and explicit.

Potential Pros:

  • Consolidates a lot of the discussion and distills from multiple blog posts, RFCs, forum threads etc.
  • Keeps the naval gazers occupied.
  • Read meat for the trolls.
  • One place for the noobs to start.
  • Endless debate can be positively focused on improving this section.
  • Enemies, friends and new comers all kept on same page
@michaelrkn

This comment has been minimized.

Copy link
Contributor

michaelrkn commented Aug 21, 2015

When I look at the proposed Breakout sections, some of them don't seem like they warrant a section all to themselves, especially:

  • Installation
  • Upgrading
  • Security
  • Deploying
  • Glossary

Each of these is probably short enough to just be a single page within some other section, except for Security, which probably should be a topic covered throughout the Guides wherever appropriate rather than being its own section.

If you remove those sections, you're left with:

  • Tutorial
  • Getting Started
  • Routing
  • Templates & Components
  • Services
  • Configuring
  • Animation
  • Classes and Objects
  • Testing
  • Data Persistence & Ember Data
  • Inspector
  • Contributing

Which is pretty much the current structure of the Guides, with Animation added.

The only difference then would be highlighting that the Tutorial should be read first, Routing, Templates/Components, and Services should be read next, and the other sections are more advanced (although I'd argue that Data/Models should be in that second grouping). I'm fine with highlighting the distinctions between those 3 groups, but we also state on the first page of the Guides (and I also think it's pretty intuitive) that the Guides are meant to be read in order, and that they start with basic, simpler information, and more advanced information comes later.

@trek

This comment has been minimized.

Copy link
Member Author

trek commented Aug 21, 2015

some of them don't seem like they warrant a section all to themselves

There is nothing to keep a section from being just a single page if that is all the content it needs. The point of the top level of ToC is discoverability.

@trek

This comment has been minimized.

Copy link
Member Author

trek commented Aug 21, 2015

that the Guides are meant to be read in order

is still true for the tutorial and core sections. It doesn't make sense for breakout topics to be read in any particular order.

But their content does need to exist. It's content that is on http://www.ember-cli.com/ and doesn't fit into another other subsection.

@michaelrkn

This comment has been minimized.

Copy link
Contributor

michaelrkn commented Aug 21, 2015

There is nothing to keep a section from being just a single page if that is all the content it needs. The point of the top level of ToC is discoverability.

The more sections there are, the less discoverable any section is. In my total uninformed unprofessional personal opinion based only my own experiences, once you get more than around 10 sections, it's overwhelming both for a new person seeing the content for the first time, and for a returning person trying to find what they're looking for. The trade-off of course is when you limit the number of sections, then it's hard to find something that doesn't quite fit into one of top-level sections. But I think search helps out a lot there (at least when it's working 😜).

@eccegordo

This comment has been minimized.

Copy link

eccegordo commented Aug 21, 2015

The more sections there are, the less discoverable any section is.

My experience is that consistency and cogency matter the most at the top level. A well thought top level hierarchy matters in that it helps hint where things beneath it are. When starting out I always felt like it was hard to find things I know I had read before in the second tier. Part of this was a mismatch with my own cognitive map of where I thought things "should be".

Maybe more more cross referencing it what matters here at the second level. There might be different keywords or phrases that rightfully should point to the same underlying content sections.

A comprehensive site map or index will go a long way towards this. I can dig up some Edward Tufte research that supports this if you would like.

@diogomafra

This comment has been minimized.

Copy link

diogomafra commented Aug 22, 2015

I have a few comments:

  • I'd include a section about "Extending Ember". This section should explain how to use ember-cli addons, bower/npm packages and how to properly use jquery components (didInsertElement...).
  • Rename the section "Inspector" to "Debugging" (inspector and tips).
  • Include a section about the release process. Maybe this can be explained in the section "Upgrading".
@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 22, 2015

@diogomafra thanks for the feedback, I've commented some of your remarks:

I'd include a section about "Extending Ember". This section should explain how to use ember-cli addons, bower/npm packages and how to properly use jquery components (didInsertElement...).

Include a section about the release process. Maybe this can be explained in the section "Upgrading".

That should be in http://emberjs.com/builds, not the guides. Especially because said explanation is going to get more expensive with the introduction of TLS.

@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 22, 2015

@eccegordo #639 (comment)

But I think there should be a section called
...

I believe part of this is to be addressed in a rewritten "Core Concepts" (see #556 (comment) an related), since the current one is more of a glossary. And another part of it is communicated, possibly in a more implicit way, by both the conventions of Ember/Ember CLI as well as the guides themselves, which should serve as documentation of the suggested current idioms.

I'd welcome feedback on the new "Core Concepts" when we get round to it.

Why services...
Why routable components vs controllers
...

I think each section's index also addressed this (at least the Ember classes) to an extent. I'm not sure the rest (Semver, learning from the competition) is a good fit for the Guides but would for example go in the Blog.
Actually I think most of these subjects have been touched on by core on blog posts and various presentations, especially learning from competition, semver, why to pick Ember (stagnation without starvation touches the latter two IMO). And controllers are addressed by my blog post :trollface:.

This plus the new Tutorial should make it a lot clearer what the recommended way to build an Ember application is. There's still work to be done to improve the prose of the sections, add diagrams, etc, follow #602 for the current effort.

@eccegordo

This comment has been minimized.

Copy link

eccegordo commented Aug 22, 2015

@locks "Core Concepts" sounds like a good category name. It sounds to me like the high level outline would look like this?

- Tutorial
---------------
- Core Concepts
- Getting Started
- Routing
- Templates & Components
- Services
---------------
...

I just want to see a single jumping off point for all the tangential conceptual stuff. The "why" of things. Along with narrative, this could also link to specific blog posts, RFCs, discussions and other areas where these concepts are enumerated in much more detail.

A user who peruses the "Core Concepts" section should have a pretty comprehensive outline and mental map of the important pieces of Ember as a system, with plenty of places to go for more info.

Stuff that is out of scope for the guides can certainly go in separate resources likes blogs, etc. Just thinking it is important to cross reference these other resources from the core concepts page as specific topics come into focus.

Ping me when you get started with this, happy to provide feedback and review.

@xud6

This comment has been minimized.

Copy link

xud6 commented Aug 22, 2015

I think breakout section maybe better become a seperate thing, maybe call it handbook.
Because I think there so many can put into it. Remove it from guide will make guide clean and simple. It can also better organized if it isn't part of guide.

@jonathanKingston

This comment has been minimized.

Copy link

jonathanKingston commented Aug 22, 2015

@michaelrkn I agree with your comment somewhat about security, as a desperate section does make it somewhat an afterthought.

However I actually think there is room for both. Some topics just won't fit within any other section than a dedicated security page/category. For example CSP and SRI both are in this category and yes! @stefanpenner I will help as much as possible. As part of my CSP RFC I will write help for adding it into your app. (I can't promise a timeline right now but certainly massive interest in helping and checking documentation here)

@michaelrkn

This comment has been minimized.

Copy link
Contributor

michaelrkn commented Aug 22, 2015

Some topics just won't fit within any other section

This is actually a good point in general - as @trek and I discussed earlier, there are several concepts (installing, upgrading, stylesheets, and CSP come to mind) that are important for every Ember dev to understand, but if they are their own section, they would just be a single page. My suggestion is to have these important but short topics covered in the tutorial - that way, every new Ember dev going through the Guides will learn about them, they will be discoverable via search for people looking for those topics, but they won't clutter the top-level sections.

@Gaurav0

This comment has been minimized.

Copy link
Contributor

Gaurav0 commented Aug 24, 2015

Where would I find information on:

  • Helpers
  • Computed Properties & Macros
  • Dependency Injection
  • Initializers
@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 24, 2015

@xudaiqing

I think breakout section maybe better become a seperate thing, maybe call it handbook.

I'd really like us not to go though another Cookbook thing.

@Gaurav0

Helpers

API docs, linked from the template section

Computed Properties & Macros

API docs, linked from whatever "Object Model" ends up as

Dependency injection

Serializers

Initializers

We're not sure we want to discuss initializers in the guides, they might just be in the ember-cli docs for addon developers. As an application developer initializers should be something that you require once in a blue moon.

@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 24, 2015

@eccegordo

@locks "Core Concepts" sounds like a good category name. It sounds to me like the high level outline would look like this?

Core concepts would be one of the guides inside the Getting Started section.

@greyhwndz

This comment has been minimized.

Copy link
Contributor

greyhwndz commented Aug 24, 2015

@locks: won't initializers be tackled in the Core concepts?

@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 24, 2015

@greyhwndz initializers are not a core concept. As I mentioned previously application developers mostly shouldn't even need to know about them.

@greyhwndz

This comment has been minimized.

Copy link
Contributor

greyhwndz commented Aug 24, 2015

@locks: ok. So where do you suggest is it best placed?

@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 24, 2015

@greyhwndz see bottom of #639 (comment)

@eccegordo

This comment has been minimized.

Copy link

eccegordo commented Aug 24, 2015

@locks said...

initializers are not a core concept. As I mentioned previously application developers mostly shouldn't even need to know about them.

This is one of those things that has historically really irked me about some of the esoteric parts of ember. They are under documented. The are lots of great primitives in the framework (Yehuda refers to them as "maximally flexible primitives").

I am all for keeping a happy path (80% use case) focus within the guides. But long term let's not overlook the advanced stuff.

I think this means a few things over the long term.

1.) API docs need really cogent examples. But more than that some commentary somewhere that explains what these things are and more importantly how you MIGHT need to use them.

2.) Probably needs to be an "Advanced Topics" section to the guides that explicitly targets the intermediate to advance ember/javascript developer and features.

3.) A section explicitly dedicated to addon developers and with that point of view. Because addons are typically crafted with different concerns than a typical app, and have to tackle much more general and ecosystem level problem domains. The better job we do training and documenting for addon developers the better everything is in the whole ecosystem for everybody else. Because so many other people can leverage the work of addons.

@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 24, 2015

@eccegordo

1.) API docs need really cogent examples.

I didn't say initializers don't need better (or any) API documentation. In fact, I wrote some of it about the before/after properties because there was no documentation about them.

2.) Probably needs to be an "Advanced Topics" section to the guides that explicitly targets the intermediate to advance ember/javascript developer and features.

We are going to address some advanced topics in the guides. We just need to write the less advanced stuff to get to those.

3.) A section explicitly dedicated to addon developers and with that point of view.

That's what the Ember CLI site is going to focus on. That's why I said initializers will probably be covered in the Ember CLI website instead, they're much more relevant to addon developers.

P.S.

This is one of those things that has historically really irked me about some of the esoteric parts of ember. They are under documented.

That's why core decided to form a documentation team, but we need time. My goal is to have kickass documentation, guides or otherwise :P

@grapho

This comment has been minimized.

Copy link
Contributor

grapho commented Aug 24, 2015

Hi! is this discussion still live, or are we merging to a discourse page? Anyway, I will help mix the pot too.

Has there been any consideration for exactly how the guides will/can be broken down and organized?

I had a thought that perhaps the guides top level structure should somewhat mimic the directory structure of a typical ember-cli based app... that way there will be a one-to-one match up of topics and where they live in your app? SOmething recognizable like that might give each guide a little bit more discoverability that some other people have mentioned?

Of course i also agree that things like "Core Concepts", "Tutorial App", "Advanced Ember", and whatnot, also deserve a top level spot toward the beginnings and ends respectively.

Edit: I realized that typically an ember-cli app is organized alphabetically... which does not really lend itself to a coherent learning path... however i think there is still some merit into breaking up the guides into those topics.. then order them by what we deem is a happy learning path.

@trek

This comment has been minimized.

Copy link
Member Author

trek commented Aug 24, 2015

Where would I find information on:
Helpers

Templates & Components

Computed Properties & Macros

Classes and Objects

Dependency Injection

Services

Initializers

Not sure. I kind of hate initializers. Can you think of a few initializer uses that aren't better met by services?

@grapho

This comment has been minimized.

Copy link
Contributor

grapho commented Aug 24, 2015

@trek would you think that helpers and mixins warrant their own sections? mixins especially are not prominently placed anywhere i can see?

I can say at least having helpers in its own section give a little more room for explaining the writing of custom helpers as well as more descriptions of all the built in helpers and what they do?

@Gaurav0

This comment has been minimized.

Copy link
Contributor

Gaurav0 commented Aug 24, 2015

@trek So the init method in services often needs to happen earlier if they involve initializing third party JavaScript libraries. I often use instance initializers to "jumpstart" services.

I use initializers to import files that do reopens of Ember library classes.

I don't mean to start a whole debate about how important initializers are. As long as the information can be found in a logical place, it really doesn't matter to me if they are in the top level or not.

@grapho

This comment has been minimized.

Copy link
Contributor

grapho commented Aug 24, 2015

+1 for initializers guides. I do not personally use them, but i recognize that a number of people still do.. also some addons.

I feel they could go back in, at least for a time, under the addons and dependencies section?

Do we want to encourage initializers long-term though? i dont know. but I still see a handful of "initializer/instance initializer deprecation" related questions, that might want a nice place to direct people to.

@trek @Gaurav0

@greyhwndz

This comment has been minimized.

Copy link
Contributor

greyhwndz commented Aug 26, 2015

Most practice that is being shared in the ember communities usually use initializers to boot their services. With services playing a significant role in lieu of the routable controllers towards routable components I guess it would be safe to say that documentation/guide on that matter would be helpful.
Leveraging addons as a means to further modularize and re-use functionality seems to be coming a common practice. So I think addons and dependencies looks sensible. Having core concepts, some basics and advanced seems to be getting apparent. I think it would be best to avoid presenting an 'alphabetized' guide primarily and something more akin of a 'journey' would map out well with the concept of a guide. A 'guide' is meant to guide and putting on the shoes of the one to be guided is I think a critical thing in achieving the goal. :+5: to all the efforts being poured in.

@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 26, 2015

Most practice that is being shared in the ember communities usually use
initializers to boot their services. With services playing a significant
role in lieu of the routable controllers towards routable components I
guess it would be safe to say that documentation/guide on that matter would
be helpful.

Most practice was written before the dependency injection mechanism was
introduced. And instance initializers.

@greyhwndz

This comment has been minimized.

Copy link
Contributor

greyhwndz commented Aug 26, 2015

@locks: I see your point. If there won't be anymore use case that merits the initializers as part of the tools to create great ember apps because of better mechanisms that are in place, then I think you have a sensible point in not including it anymore in the docu/guides. I think it's just a matter of transitioning towards the new conventions and still 'guiding' the community towards it based on the merits of their proven practices.

@Gaurav0

This comment has been minimized.

Copy link
Contributor

Gaurav0 commented Aug 26, 2015

@locks @greyhwndz It is true we no longer need initializers for dependency injection. However, there are still many use cases for them, e.g. reopening Ember classes and bootstrapping third party libraries, so I do think they should be documented somewhere.

@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 26, 2015

@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 26, 2015

@grapho

Has there been any consideration for exactly how the guides will/can be broken down and organized?

This issue is called "Improve Guides organization", and OP suggests one possible new break down.

I had a thought that perhaps the guides top level structure should somewhat mimic the directory structure of a typical ember-cli based app... that way there will be a one-to-one match up of topics and where they live in your app? SOmething recognizable like that might give each guide a little bit more discoverability that some other people have mentioned?

That would the API documentation be like. Guides should focus on concepts and use cases, and not on implementation details.

@greyhwndz

This comment has been minimized.

Copy link
Contributor

greyhwndz commented Aug 26, 2015

@Gaurav0: actually I am for having initializers, dependency injection and even addons included as part of guides. I was just somehow asking @locks if there is really merit in disregarding it despite the need.

@locks said:

I didn't say initializers don't need better (or any) API documentation. In fact, I wrote some of it about the before/after properties because there was no documentation about them.

But I think he agrees by principle that they will be included depending on the details. If it is an implementation detail then, if I am getting his line of thought, he finds that details is better found in the API documentation. I still think though that those concepts be properly placed/introduced in the conceptual 'journey' that will be traversed thru in the guides.

I think the patterns of presentation here is vital in coming up with a cohesive 'guide' and I see the API documentation, Ember-CLI section forming their respective part towards that goal. I could see the need of the tutorial as a medium of achieving that 'conceptual' journey pulling in from the API documentation. Thinking further on saying that the implementation details would need to be in the API documentation alone I think would clutter the API documentation. I was thinking a 'detailed' Tutorial that uses the API documentation. The API documentation can maintain it's topical structure without being bloated but can contain links to the appropriate links to where they stand in the conceptual guide as well as links to detailed Tutorials. That I think would help.

  • Guide Tutorial
    • will be the approach to provide the conceptual journey of the guide (that can be in the voice of our ember mascot :) ).
    • Will have levels (Basic & Advanced or however we may want this).
    • Will use the Guide Sections, Ember-CLI Sections and API documentation in providing the walkthru journeys
  • Core Sections
    • Containing the different sections of this Guide (with Basic & Advanced aspects)
    • Routing, Templates & Components, Services
    • Models & Data Persistence, Animation, Testing, Security, Debugging & Inspector
  • Ember CLI Sections
    • Installation, Setup, Asset/Dependency Management, Addons, Generators, Deployment, Upgrading
  • Glossary
  • API Documentation
    • will be constrained to the topical nature of the different classes, methods and hooks
    • providing links to the appropriate sections and tutorial phases necessary but avoiding totally creating a tutorial to hash out implementation because that would be the goal of the tutorial section.
  • How-to Contribute Section

Basically conceptual things and concrete samples everyone looking for guidance would look up to this guide as a more authoritative thing to look up to.

I hope focusing on the journey of the one that is being guided (newcomers & experienced) would lessen the technical bias that comes with being an experienced ember developer in coming up with a sensible guide that makes it easily understandable to empower them to start using and eventually further contributing to the community especially on the development side.

@locks

This comment has been minimized.

Copy link
Contributor

locks commented Aug 27, 2015

@grapho @Gaurav0 @greyhwndz send a PR that can convince both me an trek that initializers should be in the guides, and move the discussion there

@acorncom

This comment has been minimized.

Copy link
Member

acorncom commented Oct 20, 2015

Per a comment of wycat's as part of a discussion on angle-bracket components (#764 (comment)):

Anything more belongs in dedicated guides: transition from Angular, transition from React, transition from Ember curlies.

Can I suggest Upgrading -> Transitioning or some equivalent? I prefer the term Upgrading myself (as it's far clearer), but saying Upgrade from Angular (while we might all think that's the case) might be less than friendly ;-)

Not sure I'm a fan of having two sections (Upgrading and Transitioning) ...

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.