diff --git a/README b/README
index 26a53f7..e1bf59e 100644
--- a/README
+++ b/README
@@ -1,11 +1,8 @@
 Thrift (Thrift IDL and RPC tool)
-Version 1.0  (22 August 2006)
 
 Mark Slee (mcslee@facebook.com)
-Aditya Agarwal (aditya@facebook.com)
 Marc Kwiatkowski (marc@facebook.com)
-
-$Header$
+Aditya Agarwal (aditya@facebook.com)
 
 Thrift is distributed under the Thrift open source software license.
 Please see the included LICENSE file.
@@ -14,12 +11,51 @@
 ============
 
 Thrift is a lightweight, language-independent software stack with an
-associated code generation mechanism for RPC.
+associated code generation mechanism for RPC. Thrift provides clean
+abstractions for data transport, data serialization, and application
+level processing. The code generation system takes a simple definition
+language as its input and generates code across programming languages that
+uses the abstracted stack to build interoperable RPC clients and servers.
+
+For more details on Thrift's design and implementation, take a gander at
+the Thrift whitepaper included in this distribution or at the README files
+in a particular subdirectory of interest.
+
+Heirarchy
+=========
+
+thrift/
+
+  compiler/
+    Contains the Thrift compiler, implemented in C++.
+
+  lib/
+    Contains the Thrift software library implementation, subdivided by
+    language of implementation.
+
+    cpp/
+    java/
+    php/
+    py/
+    ruby/
+
+  test/
+
+    Contains sample Thrift files and test code across the target programming
+    languages.
+
 
 Requirements
 ============
-Thrift requires boost shared pointers from boost-1.33.1 or greater,
-see http://www.boost.org/libs/smart_ptr/smart_ptr.htm
+
+Thrift requires boost shared pointers from boost-1.33.1 or greater, see:
+http://www.boost.org/libs/smart_ptr/smart_ptr.htm
+
+Some portions of Thrift also depend upon libevent, see:
+http://monkey.org/~provos/libevent/
+
+These libraries are open source and may be freely obtained, but they are not
+provided as a part of this distribution.
 
 Resources
 =========
@@ -47,14 +83,17 @@
 	./configure
 
 You may need to specify the location of the boost files explicitly.
-If you installed boost in  /usr/local, you would run configure as follows:
+If you installed boost in /usr/local, you would run configure as follows:
 
 	./configure --with-boost=/usr/local
 
-Note that by default the thrift C++ library is built with no debugging symbols
-included. If you would like debugging symbols during development work, run:
+Note that by default the thrift C++ library is typically built with debugging
+symbols included. If you want to customize these options you should use the
+CXXFLAGS option in configure, as such:
 
+        ./configure CXXFLAGS='-g -O2'
         ./configure CFLAGS='-g -O2'
+        ./configure CPPFLAGS='-g -O2'
 
 Run ./configure --help to see other configuration options