get started on the documentation

README.md

@@ -1,5 +1,16 @@
 # [Nginx Server Configs](https://github.com/h5bp/server-configs-nginx)
 
+Nginx server configs is is a collection of configuration snippets that can help
+your server improve the web site's performance and security, while also
+ensuring that resources are served with the correct content-type and are
+accessible, if needed, even cross-domain.
+
+## Documentation
+
+The [documentation](/h5bp/server-configs-nginx/blob/master/doc) is bundled with
+the project, which makes it readily available for offline reading and provides a
+useful starting point for any documentation you want to write about your project.
+
 ## Contributing to this project
 
 Anyone and everyone is welcome to contribute, but please take a moment to review

doc/TOC.md

@@ -0,0 +1,14 @@
+[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
+
+# Nginx Server Configs documentation:
+
+## Getting started
+
+* [Usage](usage.md) — Overview of the project contents.
+
+## Related projects
+
+* [HTML5 Boilerplate](http://html5boilerplate.com) - professional front-end
+  template.
+* [Server configs](https://github.com/h5bp/server-configs) — Configs for
+  other web servers.

doc/usage.md

@@ -0,0 +1,84 @@
+[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
+ | [Documentation table of contents](TOC.md)
+
+# Requirements
+
+ * nginx version 1.2.1+
+
+# Usage
+
+There are two ways to make use of the contents of this repository, as a reference
+or directly as the source for nginx to run from. A number of config snippets are
+provided allowing you to pick and choose which features to allow/expose - some
+snippets are dependent on other features in this repository. For example rules that
+rely on a specific mime type for a given file extension, expect/rely the use of the
+bundled `mime.types` file.
+
+## Using as a reference
+
+To use as reference requires no special installation steps, download/checkout the
+repository to a convenient location and adapt your existing nginx configuration
+incorporating the desired functionality from this repository.
+
+## Using directly
+
+To use directly, replace the nginx config directory with this repository. for example:
+
+    /etc/init.d/nginx stop
+    cd /etc
+    mv nginx nginx-previous
+    git clone git@github.com:h5bp/server-configs-nginx.git nginx
+    # install-specific edits
+    /etc/init.d/nginx start
+
+Install specific edits will vary from server to user, minimal steps would be:
+
+ 1. verify the config in `nginx.conf` is appropriate - especially the `user` directive
+ 2. Copy `sites-available/example.com` to `sites-available/mysite.com` and edit appropriately
+ 3. Activate the new site by linking `mysite.com` into the `sites-enabled` directory
+
+## Basic structure
+
+This repository has the following structure, which is based on the standard install for a
+webserver on debian:
+
+```
+.
+├── doc
+├── h5bp
+├── sites-available
+	└── example.com
+├── sites-enabled
+├── mime.types
+└── nginx.conf
+```
+
+Below is a general description of each section
+
+### h5bp
+
+This directory contains config snippets (mixins) to be included as desired.
+There is more information available about the individual files in
+[About h5bp](h5bp.md).
+
+### doc
+
+The project documentation.
+
+### sites-available
+
+This directory should contain all of the server definitions that are available
+for use. [About sites-available](sites-available.md).
+
+### sites-enabled
+
+This directory should contain only symlinks to enable a specific `sites-available`
+server. [About sites-enabled](sites-enabled.md).
+
+### mime.types
+
+The mime.types file is responsible for mapping file extensions to mime types.
+
+### nginx.conf
+
+The main nginx config file. [About nginx.conf](nginx-conf.md).