diff --git a/docs/README.md b/docs/README.md
index f772800e5fa..6c0a21583cf 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -65,6 +65,7 @@ You can embed code snippets into a `.md`/`.mdx` file from code which lives elsew
 - In your markdown file:
     - `#include_code identifier path/from/repo/root/to/file.ts language`
     - E.g. `#include_code hello path/from/repo/root/to/file.ts typescript`
+    - See [here](docusaurus.config.js) for supported languages and the exact name to use for that language.
 - In the corresponding code delineate the code snippet with comments:
     - ```typescript
       some code
@@ -86,4 +87,32 @@ You can embed code snippets into a `.md`/`.mdx` file from code which lives elsew
       // docs:end:hello
       more code
       ```
-- Ironically, we can't show you a rendering of this, because this README.md file doesn't support the `#include_code` macro!
+- You can even include chunks of the same piece of code (with different highlighting preferences) into different parts of the docs:
+  - ```typescript
+      some code
+      some code
+      // docs:start:hello:goodbye
+      this code will appear in the 'hello' snippet and the 'goodbye' snippet.
+      this code will appear in the 'hello' snippet and the 'goodbye' snippet.
+      // this-will-error
+      this code will be highlighted red in all snippets.
+      // highlight-next-line:goodbye
+      this line will be highlighted only in the 'goodbye' snippet.
+      // highlight-start:goodbye:hello
+      this line will be highlighted in both the `hello` and `goodbye` snippets
+      this line will be highlighted in both the `hello` and `goodbye` snippets
+      // highlight-end:goodbye
+      this line will be highlighted only in the 'hello' snippet.
+      // highlight-end:hello
+      this code will appear in the 'hello' snippet and the 'goodbye' snippet.
+      // docs:end:goodbye
+      this code will appear only in the 'hello' snippet.
+      // docs:end:hello
+      some code
+      some code
+      ```
+  - Somewhere in your markdown, you can then write:
+    - `#include_code hello path/from/repo/root/to/file.ts typescript`
+  - And somewhere else, you can write:
+    - `#include_code goodbye path/from/repo/root/to/file.ts typescript`
+- Ironically, we can't show you a rendering of these examples, because this README.md file doesn't support the `#include_code` macro!
diff --git a/docs/docs/aztec/TUTORIAL-TEMPLATE.md b/docs/docs/aztec/TUTORIAL-TEMPLATE.md
index 9b11578b798..15e19093b85 100644
--- a/docs/docs/aztec/TUTORIAL-TEMPLATE.md
+++ b/docs/docs/aztec/TUTORIAL-TEMPLATE.md
@@ -10,7 +10,7 @@ This is a TEMPLATE for a "HOW TO DO SOMETHING" guide.
 
 Here are some tips on writing style:
 
-For CONSISTENCY between authors, YOU MUST use this layout and these headings.
+For CONSISTENCY between authors, YOU SHOULD use this layout and these headings.
 
 The bulk of your explanations will go in the CUSTOM HEADING sections.
 
diff --git a/docs/docs/aztec/developer/dapps/building-dapps.md b/docs/docs/aztec/developer/dapps/building-dapps.md
index f6e8fb81254..51316d161f6 100644
--- a/docs/docs/aztec/developer/dapps/building-dapps.md
+++ b/docs/docs/aztec/developer/dapps/building-dapps.md
@@ -1,15 +1,42 @@
 # Building dapps
 
-## Writing a dapp
+Please use the [TUTORIAL-TEMPLATE](../../TUTORIAL-TEMPLATE.md) for standalone guides / tutorials.
 
 Explain how to write a dapp using [`aztec.js`](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/aztec.js). Maybe that readme is enough?
 
-Please use the [TUTORIAL-TEMPLATE](../../TUTORIAL-TEMPLATE.md) for standalone guides / tutorials.
+- aztec.js 
+  - Docs outlining every typescript type.
+    - Q: can we use the tsdocs, or do we need something with a human touch (i.e. with careful explanations sandwiching the auto-generated interface data?)
+  - Docs outlining every external function:
+    - Q: can we use the tsdocs, or do we need something with a human touch (i.e. with careful explanations sandwiching the auto-generated interface data?)
+    - web3.js is nice docs.
+    - ethers.js is nice docs.
+    - Purpose of the function
+    - Parameters
+    - Return values
+    - Example of the function being used in a wider context?
+  - Walk-throughs / examples of using aztec.js for different use-cases
+    - Hopefully we can pull large code snippets directly from the e2e tests for this.
+    - We could even add way more comments to the e2e test files directly, and then use the [#include_code](../../../../README.md#include_code-macro) to pull code snippets into the docs.
+    - Use the e2e tests as inspiration.
+      - Instantiate a contract
+      - Deploy a contract
+      - How to generate a nice typescript interface for a Noir Contract's functions (we have a little `.ts` program in `noir-contracts` to generate a types file at the moment... how would a user do this?)
+      - Call 'view' functions
+      - Simulate functions (simulate the result, without sending to the 'network')
+      - Execute functions (send them to the 'network')
+      - Tx hashes and tx receipts
+      - How to query state
+      - How to query whether a tx has been 'mined'
+      - How to subscribe to logs
+      - How to filter for historic data in the historic block tree?
+      - How to query data from any of the trees (advanced)
 
-## Deploying a contract
+FOR INSTRUCTIONS FOR BUILDING A WALLET, WE SHOULD WRITE DOCS [HERE](../wallet-providers/building-a-wallet.md)
 
-Explain
+ERRORS:
+- Add any error explanations to [errors.md](./errors.md) (and break that file into multiple files if it's too unwieldy).
 
 ## Testing a dapp
 
-Write about how to test a dapp using `aztec.js`
\ No newline at end of file
+Write about how to test a dapp using `aztec.js`. Maybe this overlaps with the e2e test stuff discussed above.
\ No newline at end of file
diff --git a/docs/docs/aztec/developer/noir-contracts/compiling-contracts.md b/docs/docs/aztec/developer/noir-contracts/compiling-contracts.md
index 12ff2f17c99..ec5156a8fb0 100644
--- a/docs/docs/aztec/developer/noir-contracts/compiling-contracts.md
+++ b/docs/docs/aztec/developer/noir-contracts/compiling-contracts.md
@@ -1,13 +1,17 @@
 # Compiling contracts
 
 Please use the [TUTORIAL-TEMPLATE](../../TUTORIAL-TEMPLATE.md) for standalone guides / tutorials.
+
+:::danger TODO
+TODO: this entire page
+:::
 ## Compiling a Noir Contract
 
 You can use the `master` branch of Noir/nargo (hooray).
 
 `cd path/to/src`
 
-`nargo compile {output_artifact_name} --experimental-ssa --contracts`
+`nargo compile --contracts`
 
 > Note: the output abi json artifact file needs some manual tweaking, currently, to insert a mocked verification key. See [this script](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/src/scripts/compile.sh) (which itself calls upon the two other scripts in that file) to see how compilation and injection of the verification key is being done currently. [noir-compiler](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-compiler) is intended to replace these scripts, but ideally nargo should be outputting aztec-contract-compatible abis.
 
diff --git a/docs/docs/aztec/developer/noir-contracts/getting-started.md b/docs/docs/aztec/developer/noir-contracts/getting-started.md
index 4d7ab344d78..f7e13f64d4c 100644
--- a/docs/docs/aztec/developer/noir-contracts/getting-started.md
+++ b/docs/docs/aztec/developer/noir-contracts/getting-started.md
@@ -16,6 +16,10 @@ Download an Aztec Box. (Josh / Ze to build :) ).
 
 Or, if you don't want to do that, here's more detail on doing it all yourself:
 
+:::danger TODO
+TODO
+:::
+
 ## Creating a new contract package
 
 See [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts#creating-a-new-contract-package)
diff --git a/docs/docs/aztec/developer/noir-contracts/workflow.md b/docs/docs/aztec/developer/noir-contracts/workflow.md
index 12eddbaef52..ab184457dad 100644
--- a/docs/docs/aztec/developer/noir-contracts/workflow.md
+++ b/docs/docs/aztec/developer/noir-contracts/workflow.md
@@ -18,4 +18,4 @@
 
 ## Test
 
-[Test a deployed contract].
\ No newline at end of file
+[Test a deployed contract]. See [dapps](../dapps/building-dapps.md).
\ No newline at end of file
diff --git a/docs/docs/aztec/developer/sandbox/sandbox.md b/docs/docs/aztec/developer/sandbox/sandbox.md
index c378b14bffc..c22a6c4a642 100644
--- a/docs/docs/aztec/developer/sandbox/sandbox.md
+++ b/docs/docs/aztec/developer/sandbox/sandbox.md
@@ -3,15 +3,47 @@
 
 Please use the [TUTORIAL-TEMPLATE](../../TUTORIAL-TEMPLATE.md) for standalone guides / tutorials.
 
-## Installing the sandbox
 
-<!-- Maybe we can just copy-paste / embed from the repo? -->
+# GETTING STARTED:
 
-### Docker
+Very quick, and to the point one-pager: https://github.com/AztecProtocol/aztec-packages/issues/1406
 
-### From source
+# Questions to answer:
 
+- What is the sandbox?
+  - High level, pithy outline.
+- What can you do with the sandbox?
+  - Deploy contracts
+  - Simulate function execution
+  - Execute private and public contracts
 
-## `aztec/cli`
+- How do you download and install the sandbox?
+  - How do you do it:
+    - From up.aztec.network?
+    - From docker?
+    - From source?
 
-<!-- Maybe we can just copy-paste / embed from the repo? -->
+- How do you interact with the sandbox?
+  - @aztec/cli
+    - What is the cli?
+    - When would someone prefer using the cli over aztec.js?
+    - We should also have a detailed aztec-cli section (see below)
+  - aztec.js
+    - What is aztec.js?
+    - When would someone prefer using aztec.js over the cli?
+    - We should also have a detailed aztec.js section (see [here](../dapps/building-dapps.md))
+  - RPC calls directly?
+    - How would an advanced user make rpc calls directly to the sandbox? Can they, even?
+
+- aztec/cli
+  - Refer directly to the npm package's explanations?
+
+
+FOR INSTRUCTIONS FOR BUILDING A WALLET, WE SHOULD WRITE DOCS [HERE](../wallet-providers/building-a-wallet.md)
+
+ERRORS:
+- Add any error explanations to [errors.md](./errors.md) (and break that file into multiple files if it's too unwieldy).
+
+
+- RPC calls directly
+  - Lower priority, but eventually we should answer all of the aztec.js questions here as well.
\ No newline at end of file