craftyjs · merriam · Dec 7, 2012 · Dec 8, 2012 · Dec 9, 2012 · Dec 9, 2012
diff --git a/tutorial/bananabomber/create-a-game.md b/tutorial/bananabomber/create-a-game.md
@@ -5,14 +5,17 @@ title: Creating your first Crafty game
 
 So - let's get going!
 
-First you need to grab the latest release of the [crafty](http://www.craftyjs.com) engine. At the moment this is 0.5.0. It happens that new versions introduces breaking changes. Ask in the [forum](https://groups.google.com/forum/#!forum/craftyjs) if you run into problems. 
+First you need to [grab the latest release of the Crafty library](http://craftyjs.com/tutorial/getting-started/download-and-setup).  You should probably bookmark the [Crafty forum at GoogleGroups](https://groups.google.com/forum/#!forum/craftyjs) for when run into problems.  Of course,
+an amazing programmer like you might never run into a problem.   Also, make sure you have a handy HTML5 compliant browser such as [Chrome](https://chrome.google.com).
+Programming for Crafty is programming, so you should know some JavaScript and some HTML and have a decent editor.   
 
-Put the crafty.js file in your working directory.
-We will be working on an uncompressed version to make it easier to dig in and see what is going on. When the game is ready to be released we can replace it with a minified version that is much smaller.
+Put the *crafty.js* file in your working directory.  Be sure to use the uncompressed version of the library so that you can see what is going on while you develop:  you will use the
+minified version only when releasing the games and want the game's webpage download to be faster.  You can grab the
+latest copy of the completed game from the [Banana Bomber GitHub repository] (https://github.com/sorenbs/bananabomber/blob/master/game.js) or
+type in the examples as you go; it depends on how you learn.
 
-The game and articles is a work in progress. You can download the latest sources for the game from [github](https://github.com/sorenbs/bananabomber/blob/master/game.js)
-
-Now create the html file that will host the game:
+Your game will be in three main parts:  an HTML file to host the game, the *crafty.js* library you put in your working directory, and a *game.js* file that you will write.  Later, will add some graphics and other files.
+Start by creating the HTML file:
 
 {% highlight html %}
 <!DOCTYPE html>
@@ -30,31 +33,35 @@ Now create the html file that will host the game:
 </html>
 {% endhighlight %}
 
-The game skeleton is pretty simple:
+The HTML file is simple:  it loads two javascript libraries, sets the style to clip items that overflow a div (the overflow:hidden), and has an empty body.
+
+Now start writing *game.js* using a basic skeleton:
 
 {% highlight javascript %}
 window.onload = function () {
     //start crafty
     Crafty.init(400, 336);
-    //Crafty.canvas.init();
+    // Crafty.canvas.init();
+    // Uncomment the canvas line if using HTML Canvas instead 
 };
 {% endhighlight %}
 
-If you are familiar with javascript you will recognize this way of declaring a function that will get executed when the browser is done loading the page. In that way Crafty is no different from any other javascript you would write.
+You probably recognize the javascript construct for declaring a function that will get executed when the browser is done loading the page. 
 Crafty.init(width, height) is where Crafty does it's initialization stuff that is needed before the game can run.
-We are going to create a tile-based game so the width and height is set to multiples of 16, which is the size of the tiles.
+You are writing a tile-based game using 16x16 tiles so the width and height are set to multiples of 16.
 
-There are two ways of getting images onto the screen: 
+You get your choice of two ways of getting images onto the screen:
 
-* Using a canvas element that is like a big square of screen estate that you get to draw pixels on or 
+* Using an HTML canvas element that is like a big square of screen estate that you get to draw pixels on, or 
 * using normal DOM elements that you can manipulate using css and javascript but is drawn to the screen by the browser. 
 
-It turns out that the DOM method is fastest in most cases, but if you want to use canvas you need to call Crafty.canvas.init() first. As you will see later Crafty abstracts away most differences between DOM and canvas, so it is a matter of changing a single variable if you decide to change later.
+It turns out that the DOM method is fastest in most cases.  All you need do is call Crafty.canvas.init() first if you want to use the canvas option; Crafty abstracts away most differences between the DOM and canvas.
 
 ## Scenes
 
-To organize different parts of the game Crafty has a notion of scenes. Each level of a game would fit nicely in a scene as would the menu, high score lists etc. 
-For our simple game we will just have a loading scene and a game scene:
+Crafty has a notion of scenes to organize different parts of the game.  A complicated game might have a different sceen for each
+level of the game, each cut scene, the start menu, high score list, and achievements page.   For your simple game, you 
+will just have a loading scene and a game scene in *game.js*:
 
 {% highlight javascript %}
 //the loading screen that will display while our assets load
@@ -75,11 +82,16 @@ Crafty.scene("loading", function () {
 Crafty.scene("loading");
 {% endhighlight %}
 
-Code outside of a function will execute as the interpreter gets to it, so the last line will invoke Crafty.scene("loading") which in turn invokes the method that we have just associated with that scene.
-
-In this scene we do two things. We tell crafty to go fetch some assets that we will need (our sprite sheet) and then call a function when that is done. This function will unload the "loading" scene and load the "main" scene that will run our game. If you are not familiar with functional/dynamic languages this syntax of inlining functions might be new to you, but it is very common in javascript, so you better get used to it :-)
+Here's the order you see when you trace the exectution. If you aren't used to the syntax of inline functions as callbacks, you might need to turn your head sideways.  You will get used to it.
+// Make this a graphic?
+   * Crafty.scene("loading", function () {...}) associates a function with the "loading" scene.
+   * Crafty.scene("loading") to switch to the scene and call the function just assoicated.
+   * Crafty.load(["sprite.png"], function () {...}) to start loading resources
+   * Crafty.background() using #rgb values for black
+   * Crafty.e().text().css() to display "Loading..."
+   * Crafty.load() finishes loading *sprite.png* (our sprite sheet) and executes it finishing function, which switches to a new scene
 
-Next we define a nice background and text to display while loading. The main scene is defined in much the same way:
+The main scene is defined in much the same way:
 
 {% highlight javascript %}
 Crafty.scene("main", function () {
@@ -88,7 +100,7 @@ Crafty.scene("main", function () {
 });
 {% endhighlight %}
 
-The first thing to do in the game scene is to populate the world with background, obstacles etc. But before we get to that, let me just briefly dwell on a central part of the Crafty design.
+You will write genenerateWorld() to populate the world with background, obstacles, etc. But before we get to that, you should understand components as a central element of Crafty design.
 
 ## Components
 

diff --git a/tutorial/entities-components/providing-structure.md b/tutorial/entities-components/providing-structure.md
@@ -1,10 +1,47 @@
 ---
 layout: tutorial
-title: A Better Way to Structure your Game
+title: Everything Crafty
 ---
 
-Explain why it is better to use components to structure a game than classes and inheritance. Has-a vs is-a
+Crafty is a JavaScript library to help you build HTML5 games.  Learning the library will be easier for you if take a moment to understand the Way of Crafty, read through the vocabulary, and map these concepts to a simple game.
 
-how is it used. Add, remove, requires
+# The Crafty Way
 
-Things to note about the implementation in Crafty: No namespacing (different components will trash each others variables). object variables in components are shared among all entities with that component.
+Here is one attempt at explaining the overall choices in making Crafty.  Like the [Zen of Python] (http://www.python.org/dev/peps/pep-0020/), a short list of principles brings clarity of thought, creates focus in discussions, and is generally regarded as a great invention on par with sliced bread.
+
+**The Crafty Way**
+
+The purpose is to help make great games,
+tools are elegant when they help the purpose.
+Every game will be different,
+but there is no need to reinvent everything for each game.
+Inheritence is usually the wrong way to reuse code,
+traits are usually the right way.
+Keystroke count counts,
+but don't be mystical.
+It's better to have one complex call than ten short ones,
+but maybe we can just chain the calls together.
+Games are too small for namespaces,
+and too much organzing hurts more than it helps,
+The code should be in front of you.
+The library should fit in your head.
+
+
+# The Crafty Words
+
+Every library has a vocabulary of concepts and terms.  Each is explained in more detail somewhere else in the tutorial.
+
+### Component
+### Entity
+### Scene
+### Sprite Sheet
+
+# Spotting the Concepts in a Crafty Game
+
+Here is a simple game written in Crafty.
+
+(game in IFrame here)
+
+Look closer at the game to see how concepts fit together.
+
+(lots of screenshots here)  Side boxes to highlight components, entities, screens, and sprites.
diff --git a/tutorial/getting-started/download-and-setup.md b/tutorial/getting-started/download-and-setup.md
@@ -5,11 +5,15 @@ title: Download and Setup
 
 # Download:
 
-You can get crafty in several ways:
+You can downlad Crafty from several locations:
 
-* Main page - http://craftyjs.com
-* CraftyComponents page - http://craftycomponents.com/components/single/8/crafty
-* Crafty source on Github - https://github.com/craftyjs/Crafty
+* The home page (http://craftyjs.com) has the handy "Download Now" button, lots of demos, and other good links.
+* CraftyComponents page (http://craftycomponents.com/components/single/8/crafty) has previous versions and development branches.
+* Crafty source on Github (https://github.com/craftyjs/Crafty) with source code, the tutorial code, and other items for you to hack.
+* A minified, perhaps slowly loading, copy of a recent release (http://cdn.craftycomponents.com/crafty-release.js) can be useful when first learning Crafty.
+
+Use the right-click "Save As" to save Crafty.js to a file:  Javascript is just a single file of regular text.
+The "normal" version of the JavaScript is indented and commented while the "minified" version has been compressed by shortening symbols and removing whitespace.  This makes the miniied version faster to download into a web page.
 
 # Setup
 

diff --git a/tutorial/getting-started/how-crafty-works.md b/tutorial/getting-started/how-crafty-works.md
@@ -3,36 +3,35 @@ layout: tutorial
 title: How Crafty Works
 ---
 
-( This will be the front page of Tutorial section )
 
 # Introduction
 
-Crafty is a JavaScript game library that can help you create games in a structured way...
+Crafty is a JavaScript game library that can help you create HTML games in a structured way. 
 
-Key Features: 
+Where Crafty excels: 
 
 * Entities & Components - A clean and decoupled way to organize game elements. No inheritance needed!
 * Canvas or DOM - Choose the technology to render your entities; it will look exactly the same.
-* Eventbinding - Event system for custom events that can be triggered whenever, whatever and bound just as easily. 
+* Event binding - Event system for custom events that can be triggered whenever, whatever and bound just as easily. 
 
-Other Goodies:
+Other great Crafty benefits:
 
 * Thriving community - Help is readily available in the forum.
 * Community modules - A constantly growing collection of user-generated code you can use.
 * Pure JavaScript - No magic. Works in all major browsers and can be combined with your favorite js library.
 
 # What does a Crafty game look like
 
-Entities are the basic building blocks in Crafty. Everything in your game that needs to interact with the world is an entity. A player entity could look like this:
+An **entity** is the basic building block of Crafty. Everything in your game that needs to interact with the world is an entity. A player entity could look like this:
 
 {% highlight javascript %}
 Crafty.e("2D, DOM, Twoway").twoway(3);
 {% endhighlight %}
 
-This creates an entity that is positioned in the 2D world, is drawn to the stage using DOM elements and can be moved left and right using the arrow keys at a speed of 3 pixls pr frame.
-If this seems a little magic to you it is because I haven't introduced you to components yet.
+This creates an entity that is positioned in the 2D world, is drawn to the stage using DOM elements and can be moved left and right using the arrow keys at a speed of 3 pixels per frame.
+This seems magical until you are introduced to components.
 
-A component is a reusable piece of functionality that can be added to one or more entities. You can add components when the entity is created, as we did above, or at any later point. Components can even add more components to its host entity.
+A **component** is a reusable piece of functionality that can be added to one or more entities. You can add components when the entity is created, as we did above with _TwoWay_, or at any later point. Components can even add more components to its host entity.
 The following component moves its entity to a random place on the stage:
 
 {% highlight javascript %}
@@ -45,9 +44,9 @@ Crafty.c("RandomPosition", {
 var myEnt = Crafty.e("2D, DOM, Twoway, RandomPosition, Color").twoway(3).color("red").attr({w: 50, h: 50});
 {% endhighlight %}
 
-I also changed the size of the entity and gave it a color so you can see it. You now have a fully runnable game - go ahead and add it to the skeleton from <a href='/tutorial/getting-started/download-and-setup'>Download and setup</a> to see for yourself!
+This also changes the size of the entity and gaves it a color so you can see it. You now have a fully runnable game!   Go ahead and add it to the skeleton html page from <a href='/tutorial/getting-started/download-and-setup'>Download and setup</a> to see for yourself!
 
-Entities can react to events that occur in the game. Crafty provides a suite of build in events such as EnterFrame, Pause, SceneChange. Moving an entity one pixel to the left each frame is achieved by binding a function to the EnterFrame event
+Entities can react to events that occur in the game. Crafty provides a suite of built in events such as EnterFrame, Pause, SceneChange.  Here we bind a function to EnterFrame event to move an entity one pixel to the left before each frame:
 
 {% highlight javascript %}
 myEnt.bind("EnterFrame", function() {
@@ -57,7 +56,7 @@ myEnt.bind("EnterFrame", function() {
 
 # A simple game of pong
 
-With these simple building blocks you can create a game of two player pong complete with paddles and scoreboard in some 50 lines of javascript!
+With these simple building blocks you can create a game of two player pong complete with paddles and scoreboard in about 50 lines of javascript!
 
 {% highlight javascript %}
 Crafty.init(600, 300);

diff --git a/tutorial/index.md b/tutorial/index.md
@@ -3,7 +3,7 @@ layout: tutorial
 title: What we need
 ---
 
-Welcome to the Crafty tutorial section. This is very much a work in progress. You can find already written chapters to the left. Please help out by [forking](https://github.com/craftyjs/craftyjs.github.com)
+Welcome to the Crafty tutorial section. This is very much a work in progress. You can find already written chapters to the left. Please help out by [forking](https://github.com/craftyjs/craftyjs.github.com).
 
 
 The proposed way to structure the tutorials is to explain only one topic in each chapter. If other (perhaps more advanced) parts of Crafty are required to aid in examples and text, a reference should be given to a chapter explaining the topic in detail, and a simple explanation can be given in place.
@@ -46,7 +46,7 @@ The bananabomber chapter was written by sorenbs a while ago. I have updated it a
 * What and Why
 * Simple Game
 
-## Development Techniques
+## Development techniques
 
 * Editors
 * Debugging