2 files changed, 26 insertions, 13 deletions

diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index 69509c3..df7a717 100644
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -1,15 +1,4 @@
 = Contributing
 
-We welcome pull requests from everyone. Here are some notes that are useful for people working on meta-updater (this repository) and https://github.com/advancedtelematic/aktualizr[aktualizr].
+We welcome pull requests from everyone. It may be helpful to read the README and other documentation for link:README.adoc[this repo], https://github.com/advancedtelematic/aktualizr[aktualizr], and the https://github.com/advancedtelematic/updater-repo/[updater-repo], particularly the sections and development and debugging.
 
-== Options for local.conf/site.conf
-
-[options="header"]
-|======================
-| Option                              | Effect
-| `require classes/sota_bleeding.inc` | Always build the latest master of Aktualizr
-| `BRANCH_pn-aktualizr = "mybranch"`
-`BRANCH_pn-aktualizr-native = "mybranch"` | Build `mybranch` of Aktualizr (note that both of these need to be set). This will normally be used with `require classes/sota_bleeding.inc`
-| `SRCREV_pn-aktualizr = "1004efa3f86cef90c012b34620992b5762b741e3"`
-`SRCREV_pn-aktualizr-native = "1004efa3f86cef90c012b34620992b5762b741e3"` | Build the specified revision of Aktualizr (note that both of these need to be set).
-| `TOOLCHAIN_HOST_TASK_append = " nativesdk-cmake "` | Use with `bitbake -c populate_sdk core-image-minimal` to build a SDK
diff --git a/README.adoc b/README.adoc
index 980fa81..749bcf3 100644
--- a/README.adoc
+++ b/README.adoc
@@ -1,4 +1,6 @@
 = meta-updater
+:toc: macro
+:toc-title:
 
 This layer enables over-the-air updates (OTA) with https://github.com/ostreedev/ostree[OSTree] and https://github.com/advancedtelematic/aktualizr[Aktualizr].
 
@@ -6,6 +8,11 @@ https://github.com/ostreedev/ostree[OSTree] is a tool for atomic full file syste
 
 https://github.com/advancedtelematic/aktualizr[Aktualizr] (and https://github.com/advancedtelematic/rvi_sota_client[RVI SOTA client]) add authentication and provisioning capabilities to OTA and are integrated with OSTree. You can connect with the open-source https://github.com/advancedtelematic/rvi_sota_server[RVI SOTA server] or sign up for a free account at https://app.atsgarage.com[ATS Garage] to get started.
 
+[discrete]
+== Table of Contents
+
+toc::[]
+
 == Build
 
 === Quickstart
@@ -135,7 +142,24 @@ garage-push --repo=/path/to/ostree-repo --ref=mybranch --credentials=/path/to/cr
 
 You can set `SOTA_PACKED_CREDENTIALS` in your `local.conf` to automatically synchronize your build results with a remote server. Credentials are stored in an archive as described in the https://github.com/advancedtelematic/aktualizr/blob/master/docs/credentials.adoc[aktualizr documentation].
 
-== QA with `oe-selftest`
+== Development configuration
+
+There are a few settings that can be controlled in `local.conf` to simplify the development process:
+
+[options="header"]
+|======================
+| Option                              | Effect
+| `require classes/sota_bleeding.inc` | Build the latest head (by default, using the master branch) of Aktualizr
+| `BRANCH_pn-aktualizr = "mybranch"`
+
+`BRANCH_pn-aktualizr-native = "mybranch"` | Build `mybranch` of Aktualizr. Note that both of these need to be set. This is normally used in conjunction with `require classes/sota_bleeding.inc`
+| `SRCREV_pn-aktualizr = "1004efa3f86cef90c012b34620992b5762b741e3"`
+
+`SRCREV_pn-aktualizr-native = "1004efa3f86cef90c012b34620992b5762b741e3"` | Build the specified revision of Aktualizr. Note that both of these need to be set. This can be used in conjunction with `BRANCH_pn-aktualizr` and `BRANCH_pn-aktualizr-native` but will conflict with `require classes/sota_bleeding.inc`
+| `TOOLCHAIN_HOST_TASK_append = " nativesdk-cmake "` | Use with `bitbake -c populate_sdk core-image-minimal` to build an SDK. See the https://github.com/advancedtelematic/aktualizr#developing-against-an-openembedded-system[aktualizr repo] for more information.
+|======================
+
+== QA with oe-selftest
 
 This layer relies on the test framework oe-selftest for quality assurance. Follow the steps below to run the tests: