Improve docs

3 files changed, 11 insertions, 6 deletions

diff --git a/docs/_layouts/website/page.html b/docs/_layouts/website/page.html
index a673a48..e2dc2ea 100644
--- a/docs/_layouts/website/page.html
+++ b/docs/_layouts/website/page.html
@@ -4,6 +4,9 @@
 <a href="https://github.com/GitbookIO/gitbook/blob/master/docs/{{ file.path }}" target="_blank" class="btn btn-link pull-right hidden-xs">
     <i class="octicon octicon-mark-github"></i> Edit on GitHub
 </a>
+<a href="{{ "faq.md"|resolveFile }}" class="btn btn-link pull-right hidden-xs">
+    F.A.Q
+</a>
 <a href="https://github.com/GitbookIO/gitbook/blob/master/CHANGES.md" target="_blank" class="btn btn-link pull-right hidden-xs">
     {{ book.version }}
 </a>
diff --git a/docs/pages.md b/docs/pages.md
index 46799b3..6bff096 100644
--- a/docs/pages.md
+++ b/docs/pages.md
@@ -77,4 +77,4 @@ description: This is a short description 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.
+The front matter can define variables of your own, they will be added to the [page variable](templating/variables.md) so you can use them in your templating.
diff --git a/docs/structure.md b/docs/structure.md
index 907f3e0..02b196e 100644
--- a/docs/structure.md
+++ b/docs/structure.md
@@ -1,6 +1,8 @@
-# Directory structure
+# Directory Structure
 
-GitBook uses a simple directory structure:
+GitBook uses a simple directory structure. All Markdown/Asciidoc files listed in the [SUMMARY](pages.md) will be transformed as HTML. Multi-Lingual books have a slightly [different structure](languages.md).
+
+A basic GitBook usually looks something like this:
 
 ```
 .
@@ -21,8 +23,8 @@ An overview of what each of these does:
 | -------- | ----------- |
 | `book.json` | Stores [configuration](config.md) data (__optional__) |
 | `README.md` | Preface / Introduction for your book (**required**) |
-| `SUMMARY.md` | Table of Contents |
-
+| `SUMMARY.md` | Table of Contents (See [Pages](pages.md)) (__optional__) |
+| `GLOSSARY.md` | Lexicon / List of terms to annotate (See [Glossary](lexicon.md)) (__optional__) |
 
 ### Static files and Images
 
@@ -33,7 +35,7 @@ A static file is a file that is not listed in the `SUMMARY.md`. All static files
 GitBook will read the `.gitignore`, `.bookignore` and `.ignore` files to get a list of files and folders to skip.
 The format inside those files, follows the same convention as `.gitignore`:
 
-```markdown
+```
 # This is a comment
 
 # Ignore the file test.md