diff --git a/event_database/README.md b/event_database/README.md
index a2930d317..29e0ba974 100644
--- a/event_database/README.md
+++ b/event_database/README.md
@@ -1,40 +1,8 @@
-## Initializing a cloud BigTable instance
+# Event Database
 
-Once you've created a BigTable instance and a Service Account key, these Go scripts can create the table and column families to save event data.
+Contents
 
-Pass your BigTable connection info via args:
-- the Google Cloud projectID
-- BigTable instance name
-- the path to a GCP Service Account with appropriate permissions
-
-Invoke the script with the DB config options and `-setupDB` to create the table and column families, if they do not already exist. If they do already exists when the script runs, it will do nothing.
-
-```bash
-go run . \
-  -project your-GCP-projectID \
-  -instance your-BigTable-instance-name \
-  -keyFilePath ./service-account-key.json \
-  -setupDB
-```
-
-## Querying cloud BigTable
-
-Lookup a row by the `EmitterChain:TxID`:
-
-```bash
-go run . \
-  -project wormhole-315720 \
-  -instance wormhole \
-  -keyFilePath ./bigtable-admin.json \
-  -queryRowKey 2:000000000000000000000000e982e462b094850f12af94d21d470e21be9d0e9:6
-```
-
-Lookup all rows with a timestamp >= `queryPreviousMinutes` ago:
-
-```bash
-go run . \
-  -project wormhole-315720 \
-  -instance wormhole \
-  -keyFilePath ./bigtable-admin.json \
-  -queryPreviousMinutes 120
-```
+- `cloud_functions` functions that interact with BigTable.
+- `functions_server` an HTTP server for hosting cloud_functions locally. Used for development and running the functions for tilt devnet.
+- `initialize_db` script for initializing a table and column families.
+- `schema-docs` design documents.
diff --git a/event_database/cloud_functions/README.md b/event_database/cloud_functions/README.md
index 7d798d2ea..4f52a9e74 100644
--- a/event_database/cloud_functions/README.md
+++ b/event_database/cloud_functions/README.md
@@ -1,7 +1,30 @@
-## Google Cloud function for reading BigTable
+## Google Cloud functions for BigTable
 
 This is a reference implementaion for getting data out of BigTable.
 
+## Contents
+
+This directory holds GCP Cloud Functions, one per file, along with shared utilities in `shared.go`. The file names correspond to the hosted endpoints. ie endpoint `.../*-notionaltvl` is the file `notional-tvl.go`
+
+## Debugging with VSCode
+
+### prereqs
+
+- Golang >= 1.16 installed and available on your path.
+- The Go VSCode extension, and gopls installed.
+
+### IDE setup
+
+- open a new VSCode window
+- File menu --> "Open Workspace from File..."
+- Select `event_database/cloud_functions/workspace.code-workspace`
+
+Opening the workspace file as described above will open both `cloud_functions` and `functions_server`, so that you get all the VSCode goodness of intellesense, ability to run the code with the Go debugger, set breakpoints, etc.
+
+Add your environment variables to `functions_server/.vscode/launch.json`
+
+Start the debug server by pressing `F5`. You can check your server is up by requesting http://localhost:8080/readyz.
+
 ### deploying
 
 First deploy (creation) must include all the flags to configure the environment:
diff --git a/event_database/initialize_db/README.md b/event_database/initialize_db/README.md
new file mode 100644
index 000000000..5819912e4
--- /dev/null
+++ b/event_database/initialize_db/README.md
@@ -0,0 +1,19 @@
+## Initializing a cloud BigTable instance
+
+Once you've created a BigTable instance and a Service Account key, these Go scripts can create the table and column families to save event data.
+
+Pass your BigTable connection info via args:
+
+- the Google Cloud projectID
+- BigTable instance name
+- the path to a GCP Service Account with appropriate permissions
+
+Invoke the script with the DB config options and `-setupDB` to create the table and column families, if they do not already exist. If they do already exists when the script runs, it will do nothing.
+
+```bash
+go run . \
+  -project your-GCP-projectID \
+  -instance your-BigTable-instance-name \
+  -keyFilePath ./service-account-key.json \
+  -setupDB
+```