From c86cb764c141b5cd2de36896335ec048411cfb0b Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Thu, 15 Oct 2015 07:32:25 +0100 Subject: [PATCH] Improves Guides index --- source/index.md | 62 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 56 insertions(+), 6 deletions(-) diff --git a/source/index.md b/source/index.md index 88368cb75..819402eef 100644 --- a/source/index.md +++ b/source/index.md @@ -1,6 +1,8 @@ Welcome to the Ember.js Guides! This documentation will take you from total beginner to Ember expert. +## Organization + On the left side of each page in the Guides is a table of contents, organized into sections that can be expanded to show the topics they cover. Both the sections and the topics within each section are @@ -11,11 +13,59 @@ build Ember apps, focusing on the most widely-used features of Ember.js. For exhaustive documentation of every Ember feature and API, see the [Ember.js API documentation](http://emberjs.com/api/). -These guides are written in Markdown and are -[available on GitHub](https://github.com/emberjs/guides/). -If there is something missing, or you find a typo or -mistake, please help us by filing an issue or submitting a pull -request. You can easily jump to Github's editor for any page by -clicking the pencil icon in the upper right corner. +## Assumptions + +While we try to make the guides as beginner-friendly as we can, we must +establish a baseline so that the guides can keep focused on Ember.js +functionality. We will try to link to appropriate documentation whenever +a concept is introduced. + +To make the most out of the guides, you should have a working knowledge of: + +* **HTML, CSS, JavaScript** - the building blocks of web pages. You can find documentation of each of these technologies at the [Mozilla Developer Network][mdn]. +* **Promises** - the native way to deal with asynchrony in your JavaScript code. See the relevant [Mozilla Developer Network][promises] section. +* **ES2015 modules** - you will better understand Ember CLI's project structure and import paths if you are comfortable with [ES6 JavaScript Modules][js-modules]. +* **ES2015 syntax** - Ember CLI comes with Babel.js by default so you can +take advantage of newer language features such as arrow functions, template +strings, destructuring, and more. You can check the +[Babel.js documentation][babeljs] or read [Understanding ECMAScript 6][es6] +online. + +## Reporting a problem + +Typos, missing words, code samples with errors are all considered +documentation bugs. If you spot one of them, or want to otherwise improve +the existing guides, we are happy to help you help us! + +Some of the more common ways to report a problem with the guides are: + +* Using the pencil icon on the top-right of each guide page +* Opening an issue/pull request to [the GitHub repository][gh-guides] + +Clicking the the pencil icon will bring you to GitHub's editor for that +guide so you can edit right away, using the Markdown markup language. +This is the fastest way to correct a typo, a missing word, or an error in +a code sample. + +If you wish to make a more significant contribution be sure to check our +[issue tracker][gh-guides-issues] to see if your issue is already being +addressed. If you don't find an active issue, open a new one. + +If you have any styling questions, or about the contributing process you +can check out our [contributing guide][gh-guides-contributing]. If your +question persists, reach us at `#documentation` on the [Slack +group][slackin]. Good luck! + +[mdn]: https://developer.mozilla.org/en-US/docs/Web +[promises]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise +[js-modules]: http://jsmodules.io/ +[babeljs]: https://babeljs.io/docs/learn-es2015/ +[es6]: https://leanpub.com/understandinges6/read + +[gh-guides]: https://github.com/emberjs/guides/ +[gh-guides-issues]: https://github.com/emberjs/guides/issues +[gh-guides-contributing]: https://github.com/emberjs/guides/blob/master/CONTRIBUTING.md + +[slackin]: https://ember-community-slackin.herokuapp.com/