diff --git a/wifitables/README b/wifitables/README
deleted file mode 100644
index 1f82c1e..0000000
--- a/wifitables/README
+++ /dev/null
@@ -1,5 +0,0 @@
-WifiTables constructs tables of WiFi performance vs distance.
-
-To run:
-  ./sample at each location you want to gather measurements for.
-  ./report at the end of a series of runs to collate the data into a table.
diff --git a/wifitables/README.md b/wifitables/README.md
new file mode 100644
index 0000000..0653e1f
--- /dev/null
+++ b/wifitables/README.md
@@ -0,0 +1,214 @@
+# wifitables - construct tables of Wifi performance vs distance
+
+Developing access points requires knowing what wireless chips, and
+access points using them, do under real-world conditions of low signal strength
+and high congestion. Existing utilities are good at
+gathering the information needed to understand wireless network performance:
+
+  * [airport](http://kb.mit.edu/confluence/pages/viewpage.action?pageId=4272001)
+    on Mac, and
+    [iw](https://wireless.wiki.kernel.org/en/users/documentation/iw) on Linux,
+    to gather information on signal strength and noise
+  * [tcpdump](http://www.tcpdump.org) for information on wireless connection
+    MCS
+  * [iperf](http://sourceforge.net/projects/iperf/) for TCP and UDP throughput
+    information
+
+but using them to gather information over dozens of test runs would be tedious
+and error-prone. We wrote `wifitables` to automate this for us. Once it is 
+set up, running tests requires only a few commands:
+
+> `./sample` at each location you want to gather measurements for
+>
+> `./report` at the end of a series of runs to collate the data into a table
+
+wifitables assumes you're using a similar test environment to what we use,
+including:
+
+  * a MacOS or Linux laptop as a test client
+  * a Linux workstation as a test server
+  
+# Design Philosophy
+
+wifitables is specifically designed for experiments with signal strength
+and network congestion. These are the real-world variables that are most likely
+to affect end users' experiences, and to be overlooked by existing test 
+procedures.
+
+To control signal strength, we move one of the devices in our test network
+between tests. Increasing the distance between device and AP decreases signal
+strength. For our tests, we marked about a dozen test points through the office
+floor, starting close to my desk and extending to the far end of the floor.
+
+A busy office provides a natural experiment for congestion: both 2.4GHz and 5GHz
+(non-DFS) bands are heavily congested during the day, and lightly congested at
+night, so we repeat data collection at the same set of distances during day and
+night times.
+
+# Setting up wifitables
+
+You will need to install some software on your workstation, and on each
+computer you’re using as a test client. You don’t need to install any software
+on GFiber equipment, since it is already included in the system image.
+
+## On your workstation:
+
+  1. Install iperf
+
+        $ sudo apt-get install iperf
+
+## On each test client you want to use:
+
+  1. Install iperf. On a Mac with Homebrew installed:
+
+        $ brew install iperf
+        
+    Commands for other platforms will vary.
+
+  2. Copy wifitables to your test client. You can either clone the git
+  repository, or download an archive from Gitiles and extract it. No further
+  installation steps are required.
+  3. On a stock MacBook Pro, you’ll need to [symlink `airport` into the system
+  path](http://apple.stackexchange.com/a/130924) for the `sample` script to
+  work.
+
+# The essential test network
+
+Our access point tests take place across a local area network. This network
+includes a minimum of three hosts:
+
+  * A Fiber Network+ Box (GFRG2x0) to act as a router for the network.
+  * A host running iperf2 in TCP server mode, and running iperf2 in UDP server
+    mode, often a workstation in the lab.
+  * A laptop running test client code. This is most thoroughly tested on a
+    MacBook Pro, but Thinkpads running Ubuntu have worked as well.
+
+The WAN link of the Network+ Box is connected to a wired network with public
+Internet access; this is needed in order to manage it with the Network Tab.
+Within Google, a lab network should be used when available.
+
+The LAN links of the Network+ Box are connected to different hosts depending on
+what the objectives of the test are. These configurations are documented for
+each test network.
+
+# Networks for Access Point wireless testing
+
+These networks can be tested fully with the `sample` utility in wifitables.
+
+## Network+ Box
+
+![Network block diagram](docs/NetworkBoxTesting.png)
+
+Testing Network+ Box wireless performance requires only the elements of the
+essential test network. To physically build this network:
+
+  1. Connect your Network+ Box to the Internet.
+  2. Connect your workstation to your Network+ Box on a wired connection.
+  3. Use the Network Tab in the Fiber Portal to set up a wireless network.
+     * It’s strongly recommended to enable separate 2.4 GHz and 5 GHz SSIDs.
+  4. Join the wireless network from your laptop.
+  5. Make sure your laptop has Internet access and can ping your workstation at
+  its IP address _on the test network._
+
+## Any other Access Point
+
+![Netwok block diagram](docs/AccessPointTesting.png)
+
+Testing wireless using another Access Point requires a bit more effort to get
+set up, and the effort required varies by manufacturer. 
+
+  1. Connect the Network+ Box to the Internet, and the workstation to the
+  network box, if they are not already connected. Refer to steps 1 and 2 in
+  [Testing Network+ Box wireless](#network_box) if you haven’t done this
+  before.
+  2. In the Fiber Portal, turn *off* wireless networking on the Network+ Box.
+  Two access points in close proximity (roughly, two meters or less) will
+  interfere with each other, and you won’t get accurate test results.
+  3. Connect the AP under test to the Network+ Box using a wired connection.
+  Power it on if it has a power switch.
+  4. Perform initial configuration of the Access Point so it:
+     * serves a 5 GHz network, and
+     * is operating as a pure access point, not a router.
+
+Initial configuration is vendor-specific; for some, it will be possible to do
+over a computer wired to the Network+ Box. For others, it will be necessary to
+join their wireless network in order to do this.
+
+If the AP under test offers a firmware update during the setup process, accept
+it.
+
+Once you have completed initial configuration:
+
+  1. Join the AP's wireless network from your test laptop.
+  2. Make sure your laptop has Internet access and can ping your workstation.
+
+# Running a test series
+
+Once you’ve installed the required software, and set up your test network,
+you’re ready to start testing.
+
+_Replace_ 192.168.1.2 _with the IP address of your own workstation on the test
+network when working through these procedures._
+
+  1. Start the `iperf` servers on your workstation. I recommend running them
+  under `screen` or `tmux` so they can stay running reliably:
+
+        $ iperf -sB 192.168.1.2 -w 1M & $ iperf -usB 192.168.1.2 &
+
+  2. Determine the IP address of your workstation as seen by the Network Box.
+  3. On your test client, choose a directory that the data gathered by the test
+  script will live in. Create it if it doesn’t already exist. I use one that
+  syncs to a folder in Google Drive so the data gets shared with my team
+  automatically.
+
+        $ mkdir -p path/to/datadir
+
+  4. Choose a name for your test series. I usually choose something descriptive
+  of the test performed, like `gfrg200-day` for a test of a Network Box (model
+  number GFRG200) performed during the daytime.
+  5. Place your test client one step away from the Access Point that you’re
+  testing.
+  6. On your test client, change into the wifitables directory; if you
+  extracted the tarball in the current directory, the command will look like:
+
+        $ cd test-master/wifitables
+
+  7. Execute the sample command, specifying the journal (-j) as the name of
+  your test series, the destination (-d) as your workstation, and the number of
+  steps (-s) as 1 since you’re one step away.  
+
+        $ ./sample -j path/to/datadir/gfrg200-day -d 192.168.1.2 -s 1
+
+  8. Enter your password for `sudo` if prompted; it’s required on
+  some systems to capture wireless traffic.
+  9. Wait for the test to complete.
+  10. If this is your first series in a new environment:
+     1. step back a few steps - usually between 5 and 10 will work.
+     2. find a convenient place to set or hold your test client.
+     3. mark it with some tape and the number of steps you took.
+     4. set your test client down if you were going to do that.
+  11. If it’s not, step to the next place you have marked.
+  12. Edit the sample command to reflect the new number of steps you’re at and
+  run it:
+
+        $ ./sample -j path/to/datadir/gfrg200-day -d 192.168.1.2 -s 6
+
+  13. Go back to step 9. Repeat until your MCS drops to 0 (you no longer have a
+  signal) or you run out of room to step backwards.
+
+# Reporting on a test series
+
+Once you have gathered data for a series of tests and want to report on it, you
+can run the `report` utility from wifitables. In normal use, this
+takes a single positional argument: the series you want to report on. It will
+write the report, in tab-delimited format (.tsv), to standard output. You can
+redirect this to a file if you want.
+
+To report on the series collected earlier, you’d run
+
+    $ ./report path/to/datadir/gfrg200-day
+
+Tab-delimited text can be imported automatically by Google Sheets if you copy
+and paste it into a newly created worksheet; this is the workflow that we're
+using with this script at Google.
+
diff --git a/wifitables/docs/AccessPointTesting.png b/wifitables/docs/AccessPointTesting.png
new file mode 100644
index 0000000..08c5976
--- /dev/null
+++ b/wifitables/docs/AccessPointTesting.png
Binary files differ
diff --git a/wifitables/docs/NetworkBoxTesting.png b/wifitables/docs/NetworkBoxTesting.png
new file mode 100644
index 0000000..7113b39
--- /dev/null
+++ b/wifitables/docs/NetworkBoxTesting.png
Binary files differ