Reorganize README

1 files changed, 92 insertions, 129 deletions

diff --git a/README.md b/README.md
index f3a070d..86f7686 100644
--- a/README.md
+++ b/README.md
@@ -6,102 +6,107 @@ Dotbot is a tool that bootstraps your dotfiles (it's a [Dot]files
 control systems do more than you think.
 
 Dotbot is designed to be lightweight and self-contained, with no external
-dependencies and no installation required. Dotbot is easy to set up, and it's
-easy to configure.
+dependencies and no installation required. Dotbot can also be a drop-in
+replacement for any other tool you were using to manage your dotfiles, and
+Dotbot is VCS-agnostic -- it doesn't make any attempt to manage your dotfiles.
 
-Dotbot is VCS-agnostic, and it doesn't make any attempt to manage your
-dotfiles. Existing version control systems like git are pretty awesome at doing
-this.
+If you want an in-depth tutorial about organizing your dotfiles, see this [blog
+post][managing-dotfiles-post].
 
-Dotbot can be a drop-in replacement for any other tool you were using to manage
-your dotfiles.
+Get Running in 5 Minutes
+---------------------------
 
-Dotfiles Organization
----------------------
+### Starting Fresh?
 
-If you want an in-depth tutorial about organizing your dotfiles, see this [blog
-post][managing-dotfiles-post].
+Great! Just run the following command and start adding your customizations. If
+you're looking for [some inpiration][inspiration], we've got you covered.
 
-A great way to organize your dotfiles is having all of them in a single
-(isolated) git repository and symlinking files into place. You can add plugins
-and stuff using git submodules. This whole symlinking business can be a bit of
-work, but it's much better than just having your entire home directory under
-source control, and Dotbot can automate all of this for you and let you have a
-one-click install process, so you can have all the benefits of isolation
-without the annoyance of having to manually copy or link files.
+```bash
+  git clone git@github.com:anishathalye/dotfiles_template dotfiles
+```
 
-Dotbot itself is entirely self contained and requires no installation (it's
-self-bootstrapping), so it's not necessary to install any software before you
-provision a new machine! All you have to do is download your dotfiles and then
-run `./install`.
+### Integrate with Existing Dotfiles
 
-Template
---------
+The following will help you get set up using Dotbot in just a few steps.
 
-If you are starting fresh with your dotfiles, you can fork the [template
-repository][template]. If you want, you can rename it afterwards (to something
-like just "dotfiles"). If you're looking for inspiration, the template
-repository contains links to dotfiles repositories that use Dotbot.
+```bash
+  # replace with the path to your dotfiles
+  cd ~/.dotfiles
+  git submodule add https://github.com/anishathalye/dotbot
+  cp dotbot/tools/git-submodule/install .
+  touch install.conf.yaml
+```
 
-Setup
------
+To get started, you just need to fill in the `install.conf.yaml` and Dotbot will
+take care of the rest.  To help you get started we have [an
+example](#full-example) config file as well as [configuration
+documentation](#configuration) for the accepted parameters.
 
-Dotbot is super easy to set up. This description is given in terms of git and
-git submodules, but the procedure is similar for other VCSs.
+Note: The `install` script is merely a shim that checks out the appropriate
+version of Dotbot and calls the full Dotbot installer. By default, the script
+assumes that the configuration is located in `install.conf.yaml` the Dotbot
+submodule is located in `dotbot`. You can change either of these parameters by
+editing the variables in the `install` script appropiately.
 
-You can add Dotbot to your dotfiles by running the following command from
-within your git repository:
 
-```bash
-git submodule add https://github.com/anishathalye/dotbot
+### Full Example
+
+Here's an example of a complete configuration.
+
+The conventional name for the configuration file is `install.conf.yaml`.
+
+```yaml
+- clean: ['~']
+
+- link:
+    ~/.dotfiles: ''
+    ~/.tmux.conf: tmux.conf
+    ~/.vim: vim/
+    ~/.vimrc: vimrc
+
+- shell:
+  - [git submodule update --init --recursive, Installing submodules]
 ```
 
-This locks Dotbot on the current version. At any point, to upgrade Dotbot to
-the latest version, you can run:
+The configuration file can also be written in JSON. Here is the JSON equivalent
+of the YAML configuration given above.
+
+The conventional name for this file is `install.conf.json`.
 
-```bash
-git submodule update --remote dotbot # or other path to Dotbot submodule
+```json
+[
+    {
+        "clean": ["~"]
+    },
+    {
+        "link": {
+            "~/.dotfiles": "",
+            "~/.tmux.conf": "tmux.conf",
+            "~/.vim": "vim/",
+            "~/.vimrc": "vimrc"
+        }
+    },
+    {
+        "shell": [
+            ["git submodule update --init --recursive", "Installing submodules"]
+        ]
+    }
+]
 ```
 
-To have a one-click (one-command) install, you can place a bootstrap install
-shell script that calls Dotbot with the appropriate parameters. This script
-simply passes its arguments to Dotbot, so the script itself will not have to be
-updated once it's placed in the proper location (the Dotbot repository can be
-updated independently).
-
-An bootstrap install shell script for git is given in
-[tools/git-submodule/install][git-install]. By default, the script assumes that
-the configuration is located in `install.conf.yaml` and Dotbot is located in
-`dotbot`. The script automatically makes sure that the correct version of
-Dotbot is checked out in the submodule.
-
-This script should be **copied** into your dotfiles repository. Once the
-install script has been copied into your dotfiles, there is no need to modify
-the script again -- it is merely a shim that checks out the appropriate version
-of Dotbot and calls the full Dotbot installer. Note that using a symbolic link
-to the sample install script included in the Dotbot repository won't work
-correctly -- it can actually lead to several problems. For example, when
-cloning your dotfiles onto a new system, the Dotbot submodule won't be
-initialized (unless you use the `--recursive` flag), so the symbolic link will
-be broken, pointing to a nonexistent file.
-
-Adapting the bootstrap script for different situations (such as using a
-different VCS) is fairly straightforward.
-
-Configuration
--------------
-
-Dotbot uses YAML-formatted (or JSON-formatted) configuration files to let you
-specify how to set up your dotfiles. Currently, Dotbot knows how to `link`
-files and folders, execute `shell` commands, and `clean` directories of broken
-symbolic links.
+## Configuration
+
+Dotbot uses YAML or JSON formatted configuration files to let you specify how to
+set up your dotfiles. Currently, Dotbot knows how to [link](#link) files and
+folders, execute [shell](#shell) commands, and [clean](#clean) directories of
+broken symbolic links.
 
 **Ideally, bootstrap configurations should be idempotent. That is, the
 installer should be able to be run multiple times without causing any
 problems.** This makes a lot of things easier to do (in particular, syncing
 updates between machines becomes really easy).
 
-Dotbot configuration files are YAML (or JSON) arrays of tasks, where each task
+Dotbot configuration files are arrays of tasks, where each task
 is a dictionary that contains a command name mapping to data for that command.
 Tasks are run in the order in which they are specified. Commands within a task
 do not have a defined ordering.
@@ -124,9 +129,9 @@ a trailing "/" character.
 
 Link commands support an (optional) extended configuration. In this type of
 configuration, instead of specifying source locations directly, targets are
-mapped to extended configuration dictionaries. These dictionaries map "path" to
-the source path, specify "create" as true if the parent directory should be
-created if necessary, and specify "force" as true if the file or directory
+mapped to extended configuration dictionaries. These dictionaries map `path` to
+the source path, specify `create` as `true` if the parent directory should be
+created if necessary, and specify `force` as `true` if the file or directory
 should be forcibly linked.
 
 #### Example
@@ -151,13 +156,16 @@ base directory (that is specified when running the installer).
 #### Format
 
 Shell commands can be specified in several different ways. The simplest way is
-just to specify a command as a string containing the command to be run. Another
-way is to specify a two element array where the first element is the shell
-command and the second is an optional human-readable description. Shell
-commands support an extended syntax as well, which provides more fine-grained
-control. A command can be specified as a dictionary that contains the command
-to be run, a description, and whether stdin, stdout, and stderr are enabled. In
-this syntax, all keys are optional except for the command itself.
+just to specify a command as a string containing the command to be run.
+
+Another way is to specify a two element array where the first element is the
+shell command and the second is an optional human-readable description.
+
+Shell commands support an extended syntax as well, which provides more
+fine-grained control. A command can be specified as a dictionary that contains
+the command to be run, a description, and whether `stdin`, `stdout`, and
+`stderr` are enabled. In this syntax, all keys are optional except for the
+command itself.
 
 #### Example
 
@@ -190,50 +198,6 @@ Clean commands are specified as an array of directories to be cleaned.
 - clean: ['~']
 ```
 
-### Full Example
-
-The configuration file format is pretty simple. Here's an example of a complete
-configuration. The conventional name for the configuration file is
-`install.conf.yaml`.
-
-```yaml
-- clean: ['~']
-
-- link:
-    ~/.dotfiles: ''
-    ~/.tmux.conf: tmux.conf
-    ~/.vim: vim/
-    ~/.vimrc: vimrc
-
-- shell:
-  - [git submodule update --init --recursive, Installing submodules]
-```
-
-The configuration file can also be written in JSON. Here is the JSON equivalent
-of the YAML configuration given above. The conventional name for this file is
-`install.conf.json`.
-
-```json
-[
-    {
-        "clean": ["~"]
-    },
-    {
-        "link": {
-            "~/.dotfiles": "",
-            "~/.tmux.conf": "tmux.conf",
-            "~/.vim": "vim/",
-            "~/.vimrc": "vimrc"
-        }
-    },
-    {
-        "shell": [
-            ["git submodule update --init --recursive", "Installing submodules"]
-        ]
-    }
-]
-```
-
 Contributing
 ------------
 
@@ -246,8 +210,7 @@ License
 Copyright (c) 2014-2015 Anish Athalye. Released under the MIT License. See
 [LICENSE.md][license] for details.
 
-[template]: https://github.com/anishathalye/dotfiles_template
-[git-install]: tools/git-submodule/install
+[inspiration]: https://github.com/anishathalye/dotfiles_template#inspiration
 [managing-dotfiles-post]: http://www.anishathalye.com/2014/08/03/managing-your-dotfiles/
 [contributing]: CONTRIBUTING.md
 [license]: LICENSE.md