- restructures the docs.

- fixes many typos

1-getting-started.md

@@ -2,36 +2,8 @@
 title: Getting started
 layout: default
 permalink: "getting-started.html"
-next: "getting-started/installing.html"
 ---
 
-This guide will take you through the installation and setup of Amber
-to be used in a project.
-
-To get started with Amber and its setup and environment, we will
-create a simple TODO list application with Amber.
-
-### Some words about Amber's IDE
-
-![Helios, Amber's IDE](/images/helios.png)
-
-Unlike many other web languages/frameworks, Amber provides a fully
-integrated development environment that runs directly in the web
-browser.
-
-The IDE makes it possible to edit code live and interact with running
-objects. When served with a DAV server or the builtin amber server, it
-is also possible to commit changes to disk, freeing the developer from
-the edit/save/reload development cycle.
-
-### Saved files
-
-Amber saves packages files as [requirejs](http://requirejs.org)
-JavaScript modules containing the compiled code of Amber
-packages.
-
-Amber also saves for convenience the Smalltalk source code in separate
-`.st` files.
-
-In the next sections we will learn how to install Amber, load packages and
-fire up the development environment.
+Welcome to Amber! This quick starting guide will walk you through the
+installation process of Amber and the creation of a small Todo
+example.

2-overview.md

@@ -0,0 +1,33 @@
+---
+title: Overview
+layout: default
+permalink: "overview.html"
+next: "overview/installing.html"
+---
+
+This guide will give you an overview of Amber, it's installation
+process and setup.
+
+### How to get Amber
+
+Amber is shipped both as
+
+- a [npm module](https://npmjs.org/package/amber) for its command-line
+  interface tool `amber` with a small server, compiler and REPL;
+- a [bower](http://bower.io) component used as dependency for other
+  projects.
+
+We will see in the [next section](overview/installing.html) how
+to install both components.
+
+### How Amber manages files
+
+Amber compiles to JavaScript. It saves each package file as
+a [requirejs](http://requirejs.org) JavaScript module containing the
+compiled JavaScript code of the package.
+
+Amber also saves -- for convenience -- the Smalltalk source code of
+each package in a separate `.st` file.
+
+In the next sections we will learn how to install Amber, load and save
+packages disk and fire up the development environment.

index.md

@@ -9,14 +9,48 @@ next: getting-started.html
 This documentation is a work in progress. 
 </p>
 
-
 Welcome to the Amber documentation website!
 
-The purpose of this documentation is to guide you step by step from
-learning how to install Amber to being an advanced Amber developer.
-
 <p class="note">
 This documentation and guides are a community effort, you can
 <a href="https://github.com/amber-smalltalk/amber-documentation">contribute</a> your
 own guide!
 </p>
+
+The purpose of this documentation is to guide you step by step from
+learning how to install Amber to being an advanced Amber developer.
+
+### What is Amber?
+
+Amber is a language and development environment made for the web. The
+language is deeply inspired by
+[Smalltalk](http://en.wikipedia.org/wiki/Smalltalk), and compiles to
+JavaScript files.
+
+Amber includes a live development environment with a class browser,
+workspace, unit test runner, transcript, object inspector and
+debugger.
+
+![IDE](/images/helios.png "Amber's IDE")
+
+#### Why a Smalltalk dialect?
+
+- Smalltalk stands head and shoulders above most other languages for
+clarity, conciseness, and human-friendliness.
+
+- As a language, it is immensely clean and mature, both syntactically
+and semantically. It is a pure OO language, with objects all the way
+down.
+
+- Also, having a true live & incremental development environment where
+you can build your application interactively in the browser is
+unbeatable.
+
+#### What about the JavaScript ecosystem?
+
+Amber plays very well with the outer world. You can interact with
+JavaScript objects seamlessly, and even inspect them as any Amber
+object.
+
+Evaluating JavaScript object methods is transparent and makes using
+libraries a breeze.

getting-started/1-installing-amber.md → overview/1-installing-amber.md

@@ -2,30 +2,25 @@
 title: Installing Amber
 layout: default
 permalink: "installing.html"
-parent: Getting started
-next: "/getting-started/setting-up-project.html"
+parent: Overview
+next: "/overview/loading-amber.html"
 ---
 
-Amber is shipped both as
+### 1. The npm package
 
-- a [npm module](https://npmjs.org/package/amber) for its command-line
-  interface tool `amber` with a small server, compiler and REPL;
-- a [bower](http://bower.io) component used as dependency for other
-  projects.
+The npm package contains two command-line tools: `amber`, and `amberc`
+(the command-line compiler).
 
-### The command-line tool
-
-Using the command-line tool `amber` is not required, as any webdav
-server can serve amber files and allow packages to be committed, but
-it is a very convenient way to get started. Also, the `npm` package
-comes with a command-line compiler and a REPL.
+The `amber` tool includes a server to run on localhost
+and makes it easier to save packages to be committed on disk. It is a
+very convenient way to get started.
 
 `npm` is a package manager for [nodejs](http://nodejs.org), a
 JavaScript runtime used to run JavaScript code outside of the web
 browser.
 
 `nodejs` and `npm` can either be
-[downloaded](http://nodejs.org/download) from the website, or
+[downloadeded](http://nodejs.org/download) from the website, or
 installed using Operating System specific package managers.
 
 #### Installing nodejs on MacOS X and Windows
@@ -36,34 +31,35 @@ download the installer from the
 
 For MacOS X users, nodejs can also be installed with [homebrew](http://brew.sh/):
 
-```sh
+
+{% highlight sh %}
 brew install nodejs
-```
+{% endhighlight %}
 
 #### Installing nodejs on Ubuntu
 
 Ubuntu provides nodejs as well as npm in its repository.
 
-```sh
+{% highlight sh %}
 sudo apt-get install nodejs npm
-```
+{% endhighlight %}
 
 #### Installing the node amber package
 
 Once nodejs and npm are installed, evaluate:
 
-```sh
+{% highlight sh %}
 npm install -g amber
-```
+{% endhighlight %}
 
 Ubuntu users will have to evaluate it with `sudo`:
 
-```sh
+{% highlight sh %}
 sudo npm install -g amber
-```
+{% endhighlight %}
 
 
-### The bower component
+### 2. The bower component
 
 The npm package doesn't provide the JavaScript files required to load
 Amber in a page. This is instead provided by the bower package.
@@ -73,4 +69,29 @@ easy to manage dependencies in your application including
 Amber. Unlike npm, Bower components are meant to be used inside the
 web browser.
 
+
+```sh
+bower install amber --save
+```
+
+or by adding in the root of the project a `bower.json` file like the
+ following:
+
+{% highlight json %}
+{
+    "name": "amber-todolist",
+    "dependencies": {
+        "amber": "~0.12.3"
+    }
+}
+{% endhighlight %}
+
+and evaluating
+```sh
+bower install
+```
+
+In both cases, Amber will be installed in a directory named `bower_components`.
+
+
 We will see in the next section how to setup a project using bower.

getting-started/2-project-setup.md → overview/2-loading-amber.md

@@ -1,44 +1,10 @@
 ---
-title: Setting up the project
+title: Loading Amber
 layout: default
-permalink: "setting-up-project.html"
-parent: Getting started
+permalink: "loading-amber.html"
+parent: Overview
 ---
 
-Now that the command-line tool `amber` is installed, the project can
-be setup using bower.
-
-### Bower
-
-Bower is a package manager for the web. Amber can be install either by
-running in the root directory of the new project:
-
-```sh
-bower install amber --save
-```
-
-or by adding in the root of the project a `bower.json` file like the
- following:
-
-```json
-{
-    "name": "amber-todolist",
-    "dependencies": {
-        "amber": "~0.12.3"
-    }
-}
-```
-
-and evaluating
-```sh
-bower install
-```
-
-In both cases, Amber will be installed in a directory named `bower_components`.
-
-### Loading Amber
-
-
 In this section we will learn how setup an `index.html` page to load
 amber using [requirejs](http://requirejs.org).
 
@@ -51,10 +17,9 @@ dependencies to be loaded asynchronously.
 Amber ships with [requirejs](http://requirejs.org), the most popular
 AMD loader implementation.
 
-In the `index.html` page, both `requirejs` and `amber.js` are loaded
-as any JavaScript file:
+Create an `index.html` file with the following contents:
 
-```html
+{% highlight html %}
 <!DOCTYPE html>
 <html>
 	<head>
@@ -70,7 +35,7 @@ as any JavaScript file:
 	<body>
 	</body>
 </html> 
-```
+{% endhighlight %}
 
 In the next script we define how Amber packages are loaded. Amber
 comes with several AMD modules, the default one being `amber/devel`.