diff --git a/README b/README
index 11a7a1f..3f29420 100644
--- a/README
+++ b/README
@@ -1,24 +1,31 @@
 # HOW TO BUILD SOURCE.ANDROID.COM #
 
-source.android.com contains tutorials, references, and miscellaneous information relating to the Android Open Source Project (AOSP). The current iteration of this site is fully static HTML (notably lacking in javascript and doxygen content), and is and/or was maintained by skyler (illustrious intern under Dan Morrill and assistant to the almighty JBQ).
+source.android.com contains tutorials, references, and miscellaneous
+information relating to the Android Open Source Project (AOSP). The current
+iteration of this site is fully static HTML (notably lacking in javascript and
+doxygen content), and is and/or was maintained by skyler (illustrious intern
+under Dan Morrill and assistant to the almighty JBQ).
 
 ## Short Instructions ##
 
-Run the build script.
+Run the build script, from the same directory as this file:
 
-    build.py
+    python scripts/build.py
 
-This generates a directory html_out, which is the fully built site. Hoorah. 
+This generates the directory ./out, which is the fully built site. Hoorah. 
 
-The included micro-httpd.py script is helpful for testing the site on your own machine. 
+The included scripts/micro-httpd.py script is helpful for testing the site on
+your own machine. Running it will start up a tiny HTTP server that you can hit
+to test changes in a browser:
 
-## Less Short Instructions ##
+    cd ./out
+    HTTP_PORT=8080 python ../scripts/micro-httpd.py
 
 ### Contents Included in Box ###
 
 Necessary source files include:
 
-    site_src/   individual page content in markdown format
+    src/        individual page content in markdown format
     templates/  templates for page content
 
 and the following content which is copied directly:
@@ -29,16 +36,23 @@
 ### Structure of Site Source ###
 
 The build script assumes that
-- every .mdml file under the site_src directory is an individual page in markdown format;
-- each directory within site_src is a tab of source.android.com and contains its particular sidebar.
-  Note, the sidebar in the root of site_src/ itself is present but empty.
-
+- Every .md file under src/ is an individual page in markdown format.
+- Each directory under src/ is a tab of source.android.com and contains its
+  particular sidebar.  Note, the sidebar in the root of site_src/ itself is
+  present but empty.
+- Please use .md if possible (because this will pick up the global site CSS
+  and layout.) But the build.py script will indeed copy arbitrary files to the
+  output dir, so it is possible to simply place .html, .pdf, and similar files
+  to the src/ tree and they will be copied directly to ./out.
 
 
 # HOW TO PUSH SOURCE.ANDROID.COM TO PROD #
-
+Coming soon. For now, harass morrildl, jbq, and/or btmura.
 
 
 # SORDID HISTORY OF SOURCE.ANDROID.COM #
 
 Once upon a time, source.android.com used to be a site on Sites.
+Then it was rewritten to use the developer SDK docs, but this was hard to edit
+and overkill.
+Now it is as you see it.