Update README.md and default index.md

Seriously upgraded the README documentation.
ALso, added a tiny fix to the Kittn example in index.md.

README.md

@@ -13,13 +13,13 @@ As an example, you can check out the [TripIt API docs](http://tripit.github.io/d
 
 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.
+ - **Ruby, version 1.9.3 or newer**. It may work with older versions, but no guarantees.
+ - **Bundler**. If Ruby is already installed, but the `bundle` command doesn't work, just run `gem install bundler` in a terminal.
 
 ### Getting Set Up
 
  1. Fork this repository on Github.
- 1. Clone your repository to your hard drive with `git clone https://github.com/YOURUSERNAME/slate.git`
+ 1. Clone *your forked repository* (not our original one) 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`
@@ -28,34 +28,60 @@ You can now see the docs at <http://localhost:4567>. Whoa! That was fast!
 
 ### Making Edits
 
-Just edit the markdown file `source/index.md`! Super easy. If you know markdown, we think that the Kittn example in `source/index.md` is mostly self explanatory, but be sure to check out `syntax.md` if you need a better explanation.
+Just edit the markdown file `source/index.md`! If your middleman server is running, all you need to do is save `index.md` and reload the page in your browser to see the changes. Super easy.
+
+Syntax-wise, if you know markdown, we think that the Kittn example in `source/index.md` is mostly self explanatory, but be sure to check out [the syntax documentation](http://github.com/tripit/slate/blob/master/syntax.md) if you need a better explanation.
 
 ### Publishing Your Docs
 
 Publishing your API documentation couldn't be more simple.
 
- 1. Commit your changes to the markdown source: `git commit -a`
- 2. Push source changes to Github: `git push` (Note that at this point, we've only updated the ''markdown source'' on Github. We still haven't published the generated HTML to the `gh-pages` branch.)
- 3. Build the site, commit, and push the `gh-pages` branch: `rake publish`
+ 1. Commit your changes to the markdown source: `git commit -a -m "Update index.md"`
+ 2. Push the *markdown source* changes to Github: `git push`
+ 3. Compile to HTML, and push the HTML to Github pages: `rake publish`
 
-Done! Your changes should now be live on <http://yourusername.github.io/slate>, and the main branch should be updated with your edited markdown.
+Done! Your changes should now be live on <http://yourusername.github.io/slate>, and the main branch should be updated with your edited markdown. Note that if this is your first time publishing Slate, it can sometimes take ten minutes or so before your content is available online.
 
 ### 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.
 
-Extra Features
+FAQ
 ----------------------------------
 
-### Adding Programming Languages
+### How do I add programming languages to the tabs in the upper right corner?
+
+At the top of `index.md`, just add more languages to the list under `language-tabs`.
+
+Note that if a language is not found in `language-tabs`, we'll *always* display it. For instance, if your language tabs look like this:
+
+    language_tabs:
+      - shell
+      - ruby
 
-At the top of `index.md`, just add more languages to the list under `language-tabs`. Note that if a language is not found in `language-tabs`, we'll always display it regardless of which language is selected.
+And you have code in your markdown that looks like this:
 
-### Disable the Language Tabs
+    ```shell
+    echo "hello world"
+    ```
+
+    ```ruby
+    puts "hello world"
+    ```
+
+    ```json
+    {
+      "hello":"world"
+    }
+    ```
+
+Then the JSON will *always* be visible, since JSON isn't one of the language tabs.
+
+### How do I totally hide the language tabs?
 
 If you delete `language-tabs` altogether, we'll just completely hide the language bar.
 
-### Custom Names for the Language Tabs
+### How do I change the display name of languages in the tabs?
 
 Let's say your language tabs are like this:
 
@@ -67,20 +93,49 @@ Let's say your language tabs are like this:
 But you want "shell" to actually look like "cURL" in the tabs. You can't just change the titles of all the language blocks, since the syntax highlighter won't know what language it is. Instead, just change your `language_tabs` to look like this:
 
     language_tabs:
-      - shell:cURL
+      - shell: cURL
       - ruby
       - python
 
 Done! Language renamed. You can keep all your codeblocks for shell, but it'll look in the language bar like "cURL".
 
-### Change the Logo
+### How do I change the logo in the upper left?
 
 Just replace `source/images/logo.png` with your logo.
 
-### Getting the code to line up with the content you'd like it next to
+### How do I get my code samples to line up with the content I want them next to?
+
+Try putting code blocks and annotations right after headers. See the default `source/index.md` for an example, or file an issue if you're having trouble.
+
+### You guys recently uploaded Slate. How can I incorporate your new changes into my fork?
+
+Add the remote, call it "upstream":
+
+    git remote add upstream git@github.com:tripit/slate.git
+
+Fetch all the branches of that remote into remote-tracking branches, such as upstream/master:
+
+    git fetch upstream
+
+Make sure that you're on your master branch:
+
+    git checkout master
+
+Merge your our updates into your master branch:
+
+    git merge upstream/master
+
+Push the updated code to Github:
+
+    git push
+
+Publish the new changes to Github pages:
+
+    rake publish
 
-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.
+(Thanks to [Mark Longair on StackOverflow](http://stackoverflow.com/questions/7244321/how-to-update-github-forked-repository) for the upsteam explanation.)
 
-## Need Help?
+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!

source/index.md

@@ -137,7 +137,7 @@ curl "http://example.com/api/kittens/3"
 }
 ```
 
-This endpoint retrieves all kittens.
+This endpoint retrieves a specific kitten.
 
 ### HTTP Request