Updated "Getting Started" (with Ember CLI details) #1956
Conversation
…ser... well, started for lack of a better term. The existing "Getting Started" guide is more of a tutorial.
…mber2-getting-started Needs more cleaning up, but it looks to be a pretty good start :) Will keep chugging away on it.
… for npm install and removed links to the prod/debug/handlebars binaries. Latest sources can always be gotten from /builds
…e. Updated copy on the installing page.
… ember inspector back into "get started" area. Next up, make the splash page a bit nicer (styling, etc) for the two-liner: npm install -g ember && ember new my-app.
…de list (lvl2/3) which made font in list look horrible on Windows (d00d speak-ish)
| @@ -64,4 +64,12 @@ gem install bundler wdm tzinfo-data | |||
| gem update listen middleman | |||
| ``` | |||
|
|
|||
| Once Middleman comes up, you'll be prompted by Windows Firewall. Click "Allow access" and you'll be in business! | |||
| **NOTE**: if you get an error like this: | |||
There was a problem hiding this comment.
Stylistically, @trek and I prefer to avoid "NOTE"s. The reason is that it's easy to inject a note anywhere without having to take into account the narrative flow. Because this documentation is edited collaboratively by many people over many years, it becomes very easy for the documentation to become a torrent of "NOTE"s strung together without any real rhyme or reason. It's better to refactor the note to be part of the narrative flow. In this case, I think the paragraph stands without the "NOTE:" prefix.
There was a problem hiding this comment.
Excellent feedback re: "NOTE"s- I totally agree, even if I do have a bad habit of making them 😄 I try to use them as placeholder for needing to cleanup, which didn't happen. Will clean these occurrences up!
|
I'm torn on the Ember CLI sales pitch but the rest of it is golden. Are you able to break just that part out into a separate PR? I've also left some small stylistic/formatting notes as in-line comments. |
|
|
||
|
|
||
| ##Linter, linting, jslint, jshint | ||
| A tool ran against your JavaScript which checks for common issues. You'd usually use this in your build process to enforce quality in your codebase. A great example of something to check for: making sure you've always got your semicolons. |
There was a problem hiding this comment.
ran should be the past participle run.
|
@bsclifton AWESOME. I can understand the point with the Ember CLI salespitch, I'd personally trim down on the text and add examples. |
|
Thanks for all the great feedback folks (keep 'em coming)! I should be able to address most of the concerns outlined in the comments tonite after my son goes to sleep :) |
…ut Node.js and NPM (besides explaining the acronym mentions how it's bundled w/ node)
…"hey, this is seriously something we're including in the roadmap for 2.0"-esque. Critiques extremely welcome! Of course this section can easily be commented out in the guides yaml and put into another PR (or left out if there's not enough value).
|
Updated! ready for review |
| @@ -0,0 +1,62 @@ | |||
| ## Got Node (and NPM)? | |||
There was a problem hiding this comment.
Now that I've managed to get middleman running I understand @tomdale's comment. By opening with this section it feels more complex than it should be. Maybe move this down to "Troubleshooting" (under a sub-subheader "Installing NPM")?
As a todo for later: IMO the ember guides are big enough to have a "Troubleshooting" section where we can gather all stuff like this, grouped by category at the very bottom of the Guide sidebar.
There was a problem hiding this comment.
Excellent feedback! :) I cleaned it up locally and agree it makes much more sense under the troubleshooting
|
@bsclifton such incredible ❤️ for this PR. Sorry for the fact that some of my feedback may contradict my earlier feedback but I've only just managed to get middleman running. I think it can be trimmed down just a little more but in general I think it looks really nice. Did you deliberately leave the "Getting Ember" section in the site? |
|
Thanks again for the feedback (and thanks for checking it out live w/ Middleman)! I didn't mean to leave Getting Ember in there, good catch! I swear I removed it, but must have accidently reverted it |
|
|
||
|
|
||
| ## ES3, ES5, ES5.1, ES6, etc | ||
| The ES standing for EMCAScript and the numeral following being its spec version; basically the version of JavaScript. |
Conflicts: source/about.html.erb
|
If you want to use unordered lists, you'll need to add some CSS to give these bullets a style:
|
| Ember comes with a toolchain called Ember CLI that provides everything you need while developing your app behind a single command: ```ember```. | ||
|
|
||
| * State of the art asset management (use ```ember build``` to build your entire project) | ||
| * Quick scaffolding like ```ember generate route some-page``` |
There was a problem hiding this comment.
This sentence read awkwardly to me. I'm afraid that people who don't know what "scaffolding" is won't be aided by the ember generate… example. Maybe we can briefly describe the benefits? Something like:
Built-in generators streamline your workflow by creating ready-made files for components, models, routes and more.
- Added list style type back (it was removed in shared.css.scss). Bullets look beautiful again - Humanized the ember-cli benefits area of the install page - Small updates to the glossary
|
Will follow up with @tomdale and others today; curious what I could do to help move things along (e.g. what are the blockers?). I definitely understand if we'd like to wait and tie this to a specific release of Ember or Ember CLI. But this is great info that folks can benefit from right now, before any hero efforts are done to the doc site (versioning, etc). |
|
Pulled content over into a PR at emberjs/guides#7; the only thing that PR wouldn't cover would be the changes made to the landing page (the download ember button and npm install command, which button was updated to link to the new install section) |
|
@tomdale @trek should I go ahead and close this PR in favor of: |
Apologies for the ensuing landslide of text:
README.md has updated text; ran into a lot of issues getting emberjs/website to work on Windows (added my troubleshooting steps).
I fixed the problem with the font on Windows; the size being 13pt under 2nd/3rd level jacks things up.
Created a new "Ember CLI"-ish area at the top of the "Guide" section called "Getting Started". Instead of jumping into a tutorial, this shows details about getting started (assuming you don't have Ember installed).
a. The opening page (ember-cli/index.md) is very sales-pitch-ish, but I think that's a GOOD thing (please hear me out). Many people aren't using Ember CLI yet. They have genuine concerns about why they should switch over to this new tool, especially since it could cost their company time and money.
b. The install page has instructions on installing node.js and ember-cli.
c. Page which shows how to install the Ember Inspector
d. A glossary section. There's a lot of terms and technology that folks might not understand. This is our chance to help them :)
The previous "Getting Started Guide" (TodoMVC) has been renamed (in the guide page) "Tutorial: TodoMVC" since it is a tutorial and not a getting started guide.
Landing page - new download process. Versions are removed, since those can be found under builds. Instead, there's a link to the new install page AND markup showing how someone can install Ember CLI from the command line.
Landing page - I moved the moustache graphic all the way to the right side (the three graphics on the landing page under download). Most people's eyes go to the left and there's a bunch of moustaches hanging on a coat rack. I think it's more useful to show the developer love graphic and let them know this is a productive framework which takes care of the trivial stuff.