Restructure the docs to put more tutorials.

docs/tutorial/quick-start.md

@@ -0,0 +1,120 @@
+# Quick start
+
+## Introduction
+
+Generally, atom-shell lets you create a web-based desktop application in pure
+javascript. Unlike CEF, which requires you to use C++ to write underlying
+code, or node-webkit, which only allows you to write everything in the web
+page, atom-shell gives you the power to use javascript to control the browser
+side.
+
+## Browser and renderer
+
+Atom-shell is built upon Chromium's Content API, so it has the same
+multi-processes architecture with the Chrome browser. In summary, things about
+UI are done in the browser process, and each web page instance would start a
+new renderer process.
+
+In atom-shell, you can just put everything in a simpler way: when you are
+executing javascript in browser side, you can control the application's life,
+create UI widget, deal with system events, and create windows which contain
+web pages; while on the renderer side, you can only control the web page you
+are showing, if you want something more like creating a new window, you should
+use IPC API to tell the browser to do that.
+
+## The architecture of an app
+
+Generally, an app of atom-shell should contains at least following files:
+
+```text
+app/
+├── package.json
+├── main.js
+└── index.html
+```
+
+The format of `package.json` is exactly the same with node's modules, and the
+script specified by the `main` field is the startup script of your app, which
+will run under the browser side. An example of your `package.json` is like
+this:
+
+```json
+{
+  "name"    : "atom",
+  "version" : "0.1.0",
+  "main"    : "main.js"
+}
+```
+
+The `main.js` will be executed, and in which you should do the initialization
+work. To give the developers more power, atom-shell works by exposing
+necessary Content APIs in javascript, so developers can precisely control
+every piece of the app. An example of `main.js` is:
+
+```javascript
+var app = require('app');  // Module to control application life.
+var Window = require('window');  // Module to create native browser window.
+
+// Keep a global reference of the window object, if you don't, the window will
+// be closed automatically when the javascript object is GCed.
+var mainWindow = null;
+
+// Quit when all windows are closed.
+app.on('window-all-closed', function() {
+  app.terminate();
+});
+
+// This method will be called when atom-shell has done everything
+// initialization and ready for creating browser windows.
+app.on('ready', function() {
+  // Create the browser window,
+  mainWindow = new Window({ width: 800, height: 600 });
+  // and load the index.html of the app.
+  mainWindow.loadUrl('file://' + __dirname + '/index.html');
+
+  // Catch the event when web page in the window changes its title.
+  mainWindow.on('page-title-updated', function(event, title) {
+    // Prevent the default behaviour of 'page-title-updated' event.
+    event.preventDefault();
+
+    // Add a prefix for the window's original title.
+    this.setTitle('Atom Shell - ' + title);
+  });
+
+  // Hook to when the window is closed.
+  mainWindow.on('closed', function() {
+    // Dereference the window object, usually you would store windows
+    // in an array if your app supports multi windows, this is the time
+    // when you should delete the corresponding element.
+    mainWindow = null;
+  });
+});
+```
+
+Finally the `index.html` is the web page you want to show, in fact you
+actually don't need to provide it, you can just make the window load url of a
+remote page.
+
+## Package your app in atom-shell
+
+To make atom-shell run your app, you should name the folder of your app as
+`app`, and put it under `Atom.app/Contents/Resources/`, like this:
+
+```text
+Atom.app/Contents/Resources/app/
+├── package.json
+├── main.js
+└── index.html
+```
+
+Then atom-shell will automatically read your `package.json`. If there is no
+`Atom.app/Contents/Resources/app/`, atom-shell will load the default empty
+app, which is `Atom.app/Contents/Resources/browser/default_app/`.
+
+## IPC between browser and renderer
+
+Atom-shell provides a set of javascript APIs for developers to communicate
+between browser and renderers. There are two types of message: asynchronous
+messages and synchronous messages, the former one is quite similar with node's
+IPC APIs, while the latter one is mainly used for implement the RPC API.
+Details can be found in the `ipc` module reference.

docs/tutorial/use-native-node-module.md

@@ -0,0 +1,42 @@
+# Use native node modules
+
+Since atom-shell is using a different V8 version from the official node, you
+need to build native module against atom-shell's headers to use them.
+
+The [apm](https://github.com/atom/apm) provided a easy way to do this, after
+installing it you could use it to install dependencies just like using `npm`:
+
+```bash
+$ cd /path/to/atom-shell/project/
+$ apm install .
+```
+
+But you should notice that `apm install module` wont' work because it will
+install a user package for [Atom](https://github.com/atom/atom) instead.
+
+Apart from `apm`, you can also use `node-gyp` and `npm` to manually build the
+native modules.
+
+## The node-gyp way
+
+First you need to check which node release atom-shell is carrying via
+`process.version` (at the time of writing it is v0.10.5), then you can
+configure and build native modules via following commands:
+
+```bash
+$ cd /path-to-module/
+$ HOME=~/.atom-shell-gyp node-gyp rebuild --target=0.10.5 --arch=ia32 --dist-url=https://gh-contractor-zcbenz.s3.amazonaws.com/atom-shell/dist
+```
+
+The `HOME=~/.atom-shell-gyp` changes where to find development headers. The
+`--target=0.10.5` is specifying node's version. The `--dist-url=...` specifies
+where to download the headers.
+
+## The npm way
+
+```bash
+export npm_config_disturl=https://gh-contractor-zcbenz.s3.amazonaws.com/atom-shell/dist
+export npm_config_target=0.10.5
+export npm_config_arch=ia32
+HOME=~/.atom-shell-gyp npm install module-name
+```