Organization of Getting Started

[michaelrkn]

I keep trying to begin adding info about getting started with Ember, especially Ember CLI, and then I keep feeling like I'm going to make a mess. So I'm taking a step back, proposing an outline of what should be covered and in what order, and asking for feedback and ideas.

• Before You Start
  • Welcome (currently source/index.md)
  • Key Background Concepts (see Background info #85)
  • Core Ember Concepts (/source/concepts/core-concepts.md)
  • Other Terms (/source/ember-cli/glossary.md)
• Creating An Ember App
  • Installing Ember (source/ember-cli/index.md)
  • Ember New (move over from http://www.ember-cli.com/#folder-layout and combine source/application/index.md)
  • Ember Server (needs to be written; explain asset compilation here; this would address item 2 of Ember CLI related sections #31)
  • Ember Build (needs to be written; explain more asset compilation, fingerprinting here)
  • Windows (move over from http://www.ember-cli.com/#windows)

I figure we can hold off on topics like add-ons and configuration until a later section.

I also want to suggest breaking concepts/concepts/naming-conventions.md into pieces that are added to each of the relevant sections: for example, concepts/naming-conventions/#toc_simple-routes would be moved to routing/naming-conventions. An admirable goal of the guides is to "to start from the basics, and slowly increase to more sophisticated concepts", but naming conventions don't make any sense until you actually know what the thing is that you're naming.

Thoughts? Ideas? Suggestions?

For reference, the current structure looks like:

• Getting Started
  • Installing Ember
  • Glossary
• Getting Ember
  • Getting Ember
• Concepts
  • Core Concepts
  • Naming Conventions
• Application
  • Introduction

[Leaving out The Object Model which is stuck between Concepts and Application.]

[michaelrkn]

I've got some time to work on this over the weekend, but I want to make sure nobody has a problem with it before I sink a bunch of time into it. Any feedback before I get started?

/cc @trek @rwjblue

[trek]

I'd hold off on doing actual writing until we have time to review/respond. Unsolicited large changes to documentation, like unsolicited large changes to code, has a low likelihood of being merged, especially when there are multiple contributors all working around the same area.

We'd need a significantly longer outline before we could 👍 work that makes large organizational changes like you're proposing.

[michaelrkn]

Well I already did a bunch of stuff on it this morning :) But I'm totally happy to make changes if you don't like what I've done. Check out #135 and let me know what you think.

[michaelrkn]

Also, to make it easier to review this, I've created an outline to show how I ended up organizing things, as they're slightly different from what I originally proposed above:

• Before You Start
  • Key Background Concepts (see Background info #85)
  • Core Concepts (from /source/concepts/core-concepts.md)
  • Other Terms (from /source/ember-cli/glossary.md)
  • Installing Ember (mostly from source/ember-cli/index.md; also includes http://www.ember-cli.com/#windows)
• Ember CLI Basics
  • Creating An App (mostly from http://www.ember-cli.com/#folder-layout, with source/application/index.md combined in)
  • Running In Development (addresses item 2 of Ember CLI related sections #31)
  • Building For Production
  • Naming Conventions (from concepts/concepts/naming-conventions.md)

[trek]

@michaelrkn we obviously appreciate the effort, but there is simply higher priority guides work for 2.0 right now including getting the syntax highlighting working, replacing the getting started app, a visual redesign, removing references to Object/ArrayController, etc.

This means there just isn't time to review large unsolicited additions/reorganizations right now. You're welcome to keep working, I just don't know if anyone will have time to review. It's also entirely possible that some of your changes will be obviated by different changes taking place currently (meaning you'll be fighting a constant rebase battle).

[michaelrkn]

I'd love to help with that, and I'm sorry to have put my efforts into low-priority work here.

The only things I see highlighted as "help wanted" are #10 and #2, both of which seem like other people have already taken on. #31 looks important to me, but the last comment on there you're saying to hold off on it. I don't see issues for syntax highlighting or replacing the getting started app, removing ObjectController seems to be in progress at #81..

In other words, I'm having a tough time figuring out how to be useful :(

Can you point me in the right direction?

[bsclifton]

@michaelrkn if you're familiar with cucumber (or if you're up for rewriting the tests w/ RSpec), maybe you can help me close out #2? The plugin works great, the steps in the issue are basically cleaning up the plugin so it's done the right way. The PR I submitted hasn't been accepted yet, so you can fork off my branch if needed

[zhengjunwei]

would you please share a lazy package of all,some times the internet is very slow ,and i am not sure when the ember is ready,and i just can not wait to so many time every time.

[michaelrkn]

I'm going to close this and submit a PR for some of the more straightforward and urgent stuff I did around Ember CLI.