From 288ce6b32e3768659f5320214de9eafed8238ddf Mon Sep 17 00:00:00 2001
From: Michael DeHaan <michael.dehaan@gmail.com>
Date: Thu, 23 Feb 2012 14:40:17 -0500
Subject: [PATCH] Further readme tweaks

---
 README.md | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 88f8006c65..c86b062055 100644
--- a/README.md
+++ b/README.md
@@ -5,28 +5,38 @@ Ansible is a extra-simple Python API for doing 'remote things' over SSH.
 
 While Func, which I co-wrote, aspired to avoid using SSH and have it's own daemon infrastructure, Ansible aspires to be quite different and more minimal, but still able to grow more modularly over time. 
 
+Why use Ansible versus something else?  (Fabric, Capistrano, mCollective, Func, SaltStack, etc?) It will have far less code, it will be more correct, and it will be the easiest thing to hack on and use you'll ever see -- regardless of your favorite language of choice.
+
 Principles
 ==========
 
     * Dead simple setup
+    * Super fast & parallel by default
     * No server or client daemons, uses existing SSHd
+    * No additional software required on client boxes
+    * Everything is self updating on the clients.  "Modules" are remotely transferred to target boxes and exec'd, and do not stay active or consume resources.
     * Only SSH keys are allowed for authentication
-    * usage of ssh-agent is more or less required
+    * usage of ssh-agent is more or less required (no passwords)
     * plugins can be written in ANY language
     * as with Func, API usage is an equal citizen to CLI usage
     * use Python's multiprocessing capabilities to emulate Func's forkbomb logic
+    * all file paths can be specified as command line options easily allowing non-root usage
 
 Requirements
 ============
 
 For the server the tool is running from, *only*:
 
-    * python 2.6 -- or a backport of the multiprocessing module
+    * python 2.6 -- or the 2.4/2.5 backport of the multiprocessing module
     * paramiko
 
 Inventory file
 ==============
 
+The inventory file is a required list of hostnames that can be potentially managed by
+ansible.  Eventually this file may be editable via the CLI, but for now, is
+edited with your favorite text editor.
+
 The default inventory file (-H) is ~/.ansible_hosts and is a list
 of all hostnames to target with ansible, one per line.  These
 can be hostnames or IPs
@@ -38,10 +48,10 @@ Comamnd line usage example
 ==========================
 
 Run a module by name with arguments
-
-ssh-agent bash
-ssh-add ~/.ssh/id_rsa.pub
-ansible -p "*.example.com" -m modName -a "arg1 arg2"
+ 
+   * ssh-agent bash
+   * ssh-add ~/.ssh/id_rsa.pub
+   * ansible -p "*.example.com" -m modName -a "arg1 arg2"
 
 API Example
 ===========
@@ -67,7 +77,7 @@ Parallelism
 
 Specify the number of forks to use, to run things in greater parallelism.
 
-ansible -f 10 "*.example.com" -m modName -a "arg1 arg2"
+    * ansible -f 10 "*.example.com" -m modName -a "arg1 arg2"
 
 10 forks.  The default is 3.  5 is right out.
 
@@ -89,8 +99,12 @@ Features not supported from Func (yet?)
 Future plans
 ============
 
-   * Dead-simple declarative configuration management using
-     a runbook style recipe file
+   * modules including:
+       * users, groups, files, permissions, etc
+       * inventory gathering (w/ accompanying ansible-inventory & RSS)
+       * a command execution module
+   * Dead-simple declarative configuration management engine using
+     a runbook style recipe file, written in JSON or YAML
    * facts engine, including exec'ing facter if present
 
 Author