Update README.md

Just made some edits, added the Slate name, and fixed the code rendering issue.

README.md

 Slate
 ========
 
-Slate is a template for [Middleman](https://github.com/middleman/middleman) that turns a simple markdown file into [a beautiful API documentation page](TODOINSERTLINK).
+Slate turns a markdown file into a beautiful API documentation page for your service.
 
-For a real-world example, please see TripIt's API Documentation page, or the markdown file that is used to generate it. TODO ADD LINKS
+This is much easier to show rather than explain, so as an example please see [TripIt's API Documentation page](http://tripit.github.io/docs), which we generated with Slate. You can also view the source of the [markdown file used to generate it](http://github.com/tripit/docs/blob/master/source/index.md).
 
-Prerequisites
--------------
+### Prerequisites
 
 You're going to need:
 
  - **Ruby, version 2.0.0**
  - **Bundler**. If Ruby is already installed, but the bundle command doesn't work, just run `gem install bundler` in a terminal.
 
-Getting Set Up
---------------
+### Getting Set Up
 
  1. Fork this repository on Github.
- 1. Clone your repository with `git clone YOUR/GITHUB/URL/HERE`
- 2. `cd api-docs`
+ 1. Clone your repository to your hard drive with `git clone https://github.com/YOURUSERNAME/slate.git`
+ 2. `cd slate`
  3. Install all dependencies: `bundle install`
  4. Start the test server: `bundle exec middleman server`
 
-You can now see the docs at [http://localhost:4567]. Whoa! That was fast!
+You can now see the docs at <http://localhost:4567>. Whoa! That was fast!
 
-Making Edits
-------------
+### Making Edits
 
-Just edit the markdown file `source/index.md`! Super easy. Here's an example:
+Just edit the markdown file `source/index.md`! Super easy. Here's an example of some markdown:
 
     # This is a Major Section Header
     
@@ -66,7 +63,7 @@ Just edit the markdown file `source/index.md`! Super easy. Here's an example:
     
     > This is a code annotation that will appear in the dark area on the right
     
-  This is a bunch of text that will appear in the light-background section to the left of your docs. This is [an internal link to one of the headers above](#another-endpoint-header).
+    This is [an internal link to one of the headers above](#another-endpoint-header).
     
     This is [an external link to google](http://google.com).
     
@@ -75,8 +72,9 @@ Just edit the markdown file `source/index.md`! Super easy. Here's an example:
     which will appear | in the area | to the left | of the code
     you can add | more rows | like this | (the vertical pipes don't need to line up)
     
-Pushing Your Changes
---------------------
+You can view the rendered version of the above example at [http://tripit.github.io/slate]
+
+### Pushing Your Changes
 
 Publishing your changes couldn't be more simple.
 
@@ -86,8 +84,7 @@ Publishing your changes couldn't be more simple.
 
 Done! Your changes should now be live on [http://yourusername.github.io/slate] TODO CHANGE URL, and the main branch should be updated with your edited markdown.
 
-Don't Want to Use Github Pages?
--------------------------------
+### Don't Want to Use Github Pages?
 
 Instead of using `rake publish`, use `rake build`. Middleman will build your website to the `build` directory of your project, and you can copy those static HTML files to the server of your choice.
 
@@ -123,3 +120,11 @@ Done! Language renamed. You can keep all your codeblocks for shell, but it'll lo
 ### Change the Logo
 
 Just replace `source/images/logo.png` with your logo.
+
+### Getting the code to line up with the content you'd like it next to
+
+Because of how Slate generates the document, we recommend you put the code you'd like to appear next to some content just before that content in the markdown. We normally put our code grouped together under second level headings.
+
+## Need Help?
+
+Just submit a issue to the Slate Github if you need any help. And feel free to submit pull requests with bug fixes or changes!