diff --git a/cfg/cfg.go b/cfg/cfg.go
index b491b49..93ae060 100644
--- a/cfg/cfg.go
+++ b/cfg/cfg.go
@@ -55,5 +55,5 @@
 //          ending in .git or on GitHub can be detected to be Git. For a repo on
 //          Bitbucket we can contact the API to discover the type.
 //    - devImport: A list of development packages. Each package has the same details
-//      as those lised under import.
+//      as those listed under import.
 package cfg
diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644
index 0000000..15dcbf9
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,50 @@
+# Frequently Asked Questions (F.A.Q.)
+
+## Q: Why does Glide have the concept of sub-packages when Go doesn't?
+
+In Go every directory is a package. This works well when you have one repo containing all of your packages. When you have different packages in different VCS locations things become a bit more complicated. A project containing a collection of packages should be handled with the same information including the version. By grouping packages this way we are able to manage the related information.
+
+## Q: bzr (or hg) is not working the way I expected. Why?
+
+These are works in progress, and may need some additional tuning. Please take a look at the [vcs package](https://github.com/masterminds/vcs). If you see a better way to handle it please let us know.
+
+## Q: Should I check `vendor/` into version control?
+
+That's up to you. It's not necessary, but it may also cause you extra work and lots of extra space in your VCS. There may also be unforeseen errors ([see an example](https://github.com/mattfarina/golang-broken-vendor)).
+
+## Q: How do I import settings from GPM, Godep, or gb?
+
+There are two parts to importing.
+
+1. If a package you import has configuration for GPM, Godep, or gb Glide will recursively install the dependencies automatically.
+2. If you would like to import configuration from GPM, Godep, or gb to Glide see the `glide import` command. For example, you can run `glide import godep` for Glide to detect the projects Godep configuration and generate a `glide.yaml` file for you.
+
+Each of these will merge your existing `glide.yaml` file with the
+dependencies it finds for those managers, and then emit the file as
+output. **It will not overwrite your glide.yaml file.**
+
+You can write it to file like this:
+
+    $ glide import godep -f glide.yaml
+
+
+## Q: Can Glide fetch a package based on OS or Arch?
+
+Yes. Using the `os` and `arch` fields on a `package`, you can specify
+which OSes and architectures the package should be fetched for. For
+example, the following package will only be fetched for 64-bit
+Darwin/OSX systems:
+
+    - package: some/package
+      os:
+        - darwin
+      arch:
+        - amd64
+
+The package will not be fetched for other architectures or OSes.
+
+## Q: How did Glide get its name?
+
+Aside from being catchy, "glide" is a contraction of "Go Elide". The
+idea is to compress the tasks that normally take us lots of time into a
+just a few seconds.
diff --git a/docs/glide.yaml.md b/docs/glide.yaml.md
new file mode 100644
index 0000000..9937939
--- /dev/null
+++ b/docs/glide.yaml.md
@@ -0,0 +1,41 @@
+# The glide.yaml File
+
+The `glide.yaml` file contains information about the project and the dependent packages. Here the elements of the `glide.yaml` file are outlined.
+
+    package: github.com/Masterminds/glide
+    homepage: https://masterminds.github.io/glide
+    license: MIT
+    owners:
+    - name: Matt Butcher
+      email: technosophos@gmail.com
+      homepage: http://technosophos.com
+      - name: Matt Farina
+        email: matt@mattfarina.com
+        homepage: https://www.mattfarina.com
+    ignore:
+    - appengine
+    import:
+    - package: gopkg.in/yaml.v2
+    - package: github.com/Masterminds/vcs
+      version: ^1.2.0
+      repo:    git@github.com:Masterminds/vcs
+      vcs:     git
+    - package: github.com/codegangsta/cli
+    - package: github.com/Masterminds/semver
+      version: ^1.0.0
+
+These elements are:
+
+- `package`: The top level package is the location in the `GOPATH`. This is used for things such as making sure an import isn't also importing the top level package.
+- `homepage`: To find the place where you can find details about the package or applications. For example, http://k8s.io
+- license: The license is either an [SPDX license](http://spdx.org/licenses/) string or the filepath to the license. This allows automation and consumers to easily identify the license.
+- `owners`: The owners is a list of one or more owners for the project. This can be a person or organization and is useful for things like notifying the owners of a security issue without filing a public bug.
+- `ignore`: A list of packages for Glide to ignore importing. These are package names to ignore rather than directories.
+- `import`: A list of packages to import. Each package can include:
+  - `package`: The name of the package to import and the only non-optional item. Package names follow the same patterns the `go` tool does. That means:
+    - Package names that map to a VCS remote location end in .git, .bzr, .hg, or .svn. For example, `example.com/foo/pkg.git/subpkg`.
+    - GitHub, BitBucket, Launchpad, IBM Bluemix Services, and Go on Google Source are special cases that don't need the VCS extension.
+  - `version`: A semantic version, semantic version range, branch, tag, or commit id to use. For more information see the [versioning documentation](versions.md).
+  - `repo`: If the package name isn't the repo location or this is a private repository it can go here. The package will be checked out from the repo and put where the package name specifies. This allows using forks.
+  - `vcs`: A VCS to use such as git, hg, bzr, or svn. This is only needed when the type cannot be detected from the name. For example, a repo ending in .git or on GitHub can be detected to be Git. For a repo on Bitbucket we can contact the API to discover the type.
+- `devImport`: A list of development packages. Each package has the same details as those listed under import.
diff --git a/docs/versions.md b/docs/versions.md
new file mode 100644
index 0000000..a323fb2
--- /dev/null
+++ b/docs/versions.md
@@ -0,0 +1,50 @@
+# Versions and Ranges
+
+Glide supports [Semantic Versions](http://semver.org), SemVer ranges, branches, tags, and commit ids as versions.
+
+## Basic Ranges
+A simple range is in the form `> 1.2.3`. This tells Glide to use the latest versions that's after `1.2.3`. Glide has support for the following operators:
+
+* `=`: equal (aliased to no operator)
+* `!=`: not equal
+* `>`: greater than
+* `<`: less than
+* `>=`: greater than or equal to
+* `<=`: less than or equal to
+
+These can be combined. A `,` is an and operator and a `||` is an or operator. The or operators cause groups of and operators to be checked. For example, `">= 1.2, < 3.0.0 || >= 4.2.3"`.
+
+## Hyphen Ranges
+
+There are multiple shortcuts to handle ranges and the first is hyphens ranges. These look like:
+
+* `1.2 - 1.4.5` which is equivalent to `>= 1.2, <= 1.4.5`
+* `2.3.4 - 4.5` which is equivalent to `>= 2.3.4, <= 4.5`
+
+## Wildcards In Comparisons
+
+The `x`, `X`, and `*` characters can be used as a wildcard character. This works for all comparison operators. When used on the `=` operator it falls back to the patch level comparison (see tilde below). For example,
+
+* `1.2.x` is equivalent to `>= 1.2.0, < 1.3.0`
+* `>= 1.2.x` is equivalent to `>= 1.2.0`
+* `<= 2.x` is equivalent to `<= 3`
+* `*` is equivalent to `>= 0.0.0`
+
+## Tilde Range Comparisons (Patch)
+
+The tilde (`~`) comparison operator is for patch level ranges when a minor version is specified and major level changes when the minor number is missing. For example,
+
+* `~1.2.3` is equivalent to `>= 1.2.3, < 1.3.0`
+* `~1` is equivalent to `>= 1, < 2`
+* `~2.3` is equivalent to `>= 2.3, < 2.4`
+* `~1.2.x` is equivalent to `>= 1.2.0, < 1.3.0`
+* `~1.x` is equivalent to `>= 1, < 2`
+
+## Caret Range Comparisons (Major)
+
+The caret (`^`) comparison operator is for major level changes. This is useful when comparisons of API versions as a major change is API breaking. For example,
+
+* `^1.2.3` is equivalent to `>= 1.2.3, < 2.0.0`
+* `^1.2.x` is equivalent to `>= 1.2.0, < 2.0.0`
+* `^2.3` is equivalent to `>= 2.3, < 3`
+* `^2.x` is equivalent to `>= 2.0.0, < 3`
diff --git a/mkdocs.yml b/mkdocs.yml
index 5b994bb..7064e9c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -2,4 +2,7 @@
 pages:
 - Home: index.md
 - Getting Started: getting-started.md
+- The glide.yaml File: glide.yaml.md
+- Versions and Ranges: versions.md
+- F.A.Q.: faq.md
 theme: readthedocs