Reviewing, first part

9 files changed, 71 insertions, 38 deletions

diff --git a/docs/README.md b/docs/README.md
index 6febb43..12b0e6c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,7 +4,7 @@
 
 GitBook is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc). Here is an example: [Learn Javascript](https://www.gitbook.com/book/GitBookIO/javascript). This documentation has been generated using GitBook.
 
-GitBook can output your content as a website ([customizable](themes.md) and [extensibles](plugins.md)) or as an ebook (PDF, ePub or Mobi).
+GitBook can output your content as a website ([customizable](themes/README.md) and [extensibles](plugins/README.md)) or as an ebook (PDF, ePub or Mobi).
 
 [GitBook.com](https://www.gitbook.com) is the online platform to create and host books built using the GitBook format. It offers hosting, collaboration features and an [easy-to-use editor](https://www.gitbook.com/editor).
 
@@ -14,7 +14,7 @@ We're always happy to help out with your books or any other questions you might
 
 ### FAQ
 
-There are questions that are asked quite often, [check this out before creating an issue](faq.md).
+Some questions are frequently asked. If you have a problem you should  [check this out](faq.md) first.
 
 ### Contribute to this documentation
 
diff --git a/docs/asciidoc.md b/docs/asciidoc.md
index c04098b..0dfbb41 100644
--- a/docs/asciidoc.md
+++ b/docs/asciidoc.md
@@ -8,11 +8,11 @@ Just like for markdown, GitBook is using some special files to extract structure
 
 ### README.adoc
 
-This is the main entry of your book: the introduction. This file is **non optional**.
+This is the main entry of your book: the introduction. This file is **required**.
 
 ### SUMMARY.adoc
 
-This file defines the list of chapters and subchapters. Just like [for markdown](./pages.md), the `SUMMARY.adoc`'s format is simply a list of links, the name of the link is used as the chapter's name, and the target is a path to that chapter's file.
+This file defines the list of chapters and subchapters. Just like  in Markdown, the `SUMMARY.adoc`'s format is simply a list of links, the name of the link is used as the chapter's name, and the target is a path to that chapter's file.
 
 Subchapters are defined simply by adding a nested list to a parent chapter.
 
diff --git a/docs/config.md b/docs/config.md
index de3816b..fc9b411 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -1,21 +1,28 @@
 # Configuration
 
-GitBook allows you to customize your book using a flexible configuration. These options are specified in a `book.json` file. For authors, not used to write JSON, you can validate the syntax using [jsonlint](http://jsonlint.com).
+GitBook allows you to customize your book using a flexible configuration. These options are specified in a `book.json` file. For authors unfamiliar with the JSON syntax, you can validate the syntax using tools such as [JSONlint](http://jsonlint.com).
 
-### Configuration Settings
+### General Settings
 
 | Variable | Description |
 | -------- | ----------- |
-| `root` | Path to the root folder containing the content |
+| `root` | Path to the root folder containing all the book's files, except `book.json`|
 | `title` | Title of your book, default value is extracted from the README. On GitBook.com this field is pre-filled. |
 | `description` | Description of your book, default value is extracted from the README. On GitBook.com this field is pre-filled. |
 | `author` | Name of the author. On GitBook.com this field is pre-filled. |
 | `isbn` | ISBN of the book |
-| `language` | ISO code of the book's language, default value is `en` |
-| `direction` | `rtl` or `ltr`, default value depends on the value of `language` |
-| `gitbook` | [SemVer](http://semver.org) condition to validate which GitBook version should be used |
-| `plugins` | List of plugins to load, See [the plugins section](plugins/README.md) for more details |
-| `pluginsConfig` |Configuration for plugins, See [the plugins section](plugins/README.md) for more details |
+| `language` | [ISO code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) of the book's language, default value is `en` |
+| `direction` | Text's direction. Can be `rtl` or `ltr`, the default value depends on the value of `language` |
+| `gitbook` | Version of GitBook that should be used. Uses the [SemVer](http://semver.org) specification and accepts conditions like `">= 3.0.0"` |
+
+### Plugins
+
+Plugins and their configurations are specified in the `book.json`. See [the plugins section](plugins/README.md) for more details.
+
+| Variable | Description |
+| -------- | ----------- |
+| `plugins` | List of plugins to load |
+| `pluginsConfig` |Configuration for plugins |
 
 ### PDF Options
 
@@ -31,8 +38,3 @@ PDF Output can be customized using a set of options in the `book.json`:
 | `pdf.margin.bottom` | Bottom margin (default is `56`) |
 | `pdf.margin.right` | Right margin (default is `62`) |
 | `pdf.margin.left` | Left margin (default is `62`) |
-
-### Plugins
-
-Plugins and their configurations are specified in the `book.json`. See [the plugins section](plugins/README.md) for more details.
-
diff --git a/docs/faq.md b/docs/faq.md
index 42de8fe..ff3628e 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -26,7 +26,7 @@ GitBook supports math equations and TeX thanks to plugins. There are currently 2
 
 #### Can I customize/theme the output?
 
-Yes, both the website and ebook outputs can be customized using [themes](themes.md).
+Yes, both the website and ebook outputs can be customized using [themes](themes/README.md).
 
 #### Can I add interactive content (videos, etc)?
 
diff --git a/docs/languages.md b/docs/languages.md
index 0cb5801..6afbd4e 100644
--- a/docs/languages.md
+++ b/docs/languages.md
@@ -14,4 +14,4 @@ GitBook supports building books written in multiple languages. Each language sho
 
 When a language book (ex: `en`) has a `book.json`, its configuration will extend the main configuration.
 
-The only exception is plugins, plugins are specify globally relative to the book, and language specific plugins can not be specified.
+The only exception is plugins, plugins are specified globally, and language specific plugins cannot be specified.
diff --git a/docs/lexicon.md b/docs/lexicon.md
index 5d356b4..5740139 100644
--- a/docs/lexicon.md
+++ b/docs/lexicon.md
@@ -1,6 +1,6 @@
 # Glossary
 
-Allows you to specify terms and their respective definitions to be displayed as annotations. Based on those terms, gitbook will automatically build an index and highlight those terms in pages.
+Allows you to specify terms and their respective definitions to be displayed as annotations. Based on those terms, GitBook will automatically build an index and highlight those terms in pages.
 
 The `GLOSSARY.md` format is very simple :
 
@@ -9,5 +9,6 @@ The `GLOSSARY.md` format is very simple :
 Definition for this term
 
 # Another term
-With it's definition, this can contain bold text and all other kinds of inline markup ...
-```
\ No newline at end of file
+With it's definition, this can contain bold text
+and all other kinds of inline markup ...
+```
diff --git a/docs/pages.md b/docs/pages.md
index 8ffa054..46799b3 100644
--- a/docs/pages.md
+++ b/docs/pages.md
@@ -1,12 +1,12 @@
 # Pages and Summary
 
-GitBook uses a `SUMMARY.md` file to define the structure of chapters and subchapters of the book. The `SUMMARY.md` file is used to generate the book's table of contents.
-
 ### Summary
 
-The `SUMMARY.md`'s format is simply a list of links, the title of the link is used as the chapter's title, and the target is a path to that chapter's file.
+GitBook uses a `SUMMARY.md` file to define the structure of chapters and subchapters of the book. The `SUMMARY.md` file is used to generate the book's table of contents.
 
-Subchapters are defined simply by adding a nested list to a parent chapter.
+The format of `SUMMARY.md` is just a list of links. The link's title is used as the chapter's title, and the link's target is a path to that chapter's file.
+
+Adding a nested list to a parent chapter will create subchapters.
 
 ##### Simple example
 
@@ -21,23 +21,50 @@ Subchapters are defined simply by adding a nested list to a parent chapter.
     * [Better tools for authors](part2/better_tools.md)
 ```
 
+Each chapter has a dedicated page (`part#/README.md`) and is split into subchapters.
+
 ##### Example with subchapters split into parts
 
 ```markdown
 # Summary
 
-### Part 1
+### Part I
 
 * [Writing is nice](part1/writing.md)
 * [GitBook is nice](part1/gitbook.md)
 
-### Part 2
+### Part II
 
 * [We love feedback](part2/feedback_please.md)
 * [Better tools for authors](part2/better_tools.md)
 ```
 
-### Front Matter
+Here, parts are just groups of chapters and do not have dedicated pages, but will show in the navigation for example.
+
+### Pages
+
+#### Markdown syntax
+
+Most of the files for GitBook use the Markdown syntax by default. GitBook infers your pages's structure from it. The syntax used is similar to the [GitHub Flavored Markdown syntax](https://guides.github.com/features/mastering-markdown/). One can also opt for the [AsciiDoc syntax](asciidoc.md).
+
+##### Example of a chapter file
+
+``` markdown
+# Title of the chapter
+
+This is a great introduction.
+
+## Section 1
+
+Markdown will dictates _most_ of your **book's structure**
+
+## Section 2
+
+...
+
+```
+
+#### Front Matter
 
 Pages can contain an optional front matter. It can be used to define the page's description. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:
 
@@ -47,4 +74,7 @@ description: This is a short description of my page
 ---
 
 # The content of my page
+...
 ```
+
+The front matter can define variables of your own, they will be added to the [book variable](templating/variables.md) so you can use them in your templating.
diff --git a/docs/setup.md b/docs/setup.md
index 764dedd..878fe57 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -4,7 +4,7 @@ Getting GitBook installed and ready-to-go should only take a few minutes.
 
 ### GitBook.com
 
-[GitBook.com](https://www.gitbook.com) is an easy to use solution to write, publish and host books. It's best and easier solution for publishing your content and collaborate on it.
+[GitBook.com](https://www.gitbook.com) is an easy to use solution to write, publish and host books. It is the easiest solution for publishing your content and collaborating on it.
 
 It integrates well with the [GitBook Editor](https://www.gitbook.com/editor).
 
@@ -12,7 +12,7 @@ It integrates well with the [GitBook Editor](https://www.gitbook.com/editor).
 
 ##### Requirements
 
-Installing GitBook is easy and straight-forward, but there are a few requirements you’ll need to make sure your system has before you start.
+Installing GitBook is easy and straightforward. Your system just needs to meet these two requirements:
 
 * NodeJS (v4.0.0 and above are adviced)
 * Windows, Linux, Unix, or Mac OS X
@@ -25,7 +25,7 @@ The best way to install GitBook is via **NPM**. At the terminal prompt, simply r
 $ npm install gitbook-cli -g
 ```
 
-`gitbook-cli` is an utility to install and use multiple versions of GitBook on the same system. It will automatically install the required version to build a book.
+`gitbook-cli` is an utility to install and use multiple versions of GitBook on the same system. It will automatically install the required version of GitBook to build a book.
 
 ##### Create a book
 
@@ -43,7 +43,7 @@ Preview and serve your book using:
 $ gitbook serve
 ```
 
-or build the static website using:
+Or build the static website using:
 
 ```
 $ gitbook build
@@ -51,7 +51,7 @@ $ gitbook build
 
 ##### Install pre-releases
 
-`gitbook-cli` makes it easy to install and test other versions of GitBook with your book:
+`gitbook-cli` makes it easy to download and install other versions of GitBook to test with your book:
 
 ```
 $ gitbook fetch beta
diff --git a/docs/structure.md b/docs/structure.md
index a811bd9..907f3e0 100644
--- a/docs/structure.md
+++ b/docs/structure.md
@@ -1,6 +1,6 @@
 # Directory structure
 
-GitBook uses a very simple and obvious directory structure:
+GitBook uses a simple directory structure:
 
 ```
 .
@@ -26,7 +26,7 @@ An overview of what each of these does:
 
 ### Static files and Images
 
-A static file is a file that is not listed in the `SUMMARY.md`. All static files, not [ignored](#ignore), are copied to the output.
+A static file is a file that is not listed in the `SUMMARY.md`. All static files, unless [ignored](#ignore), are copied to the output.
 
 ### Ignoring files & folders {#ignore}
 
@@ -43,9 +43,9 @@ test.md
 bin/*
 ```
 
-### Project documentation / Sub-directory {#subdirectory}
+### Project integration with subdirectory {#subdirectory}
 
-For software project, it sometimes better to use a diretcory (like `docs/`) to store the project's documentation. You can use the [`root` option](config.md) to indicate to GitBook in which folder the book is stored:
+For software projects, you can use a subdirectory (like `docs/`) to store the book for the project's documentation. You can configure the [`root` option](config.md) to indicate the folder where GitBook can find the book's files:
 
 ```
 .