Add a little bit more development documentation to the root readme.

README.adoc

@@ -31,12 +31,40 @@ the README document in the subfolders for their current purpose and status.
 
 = Development
 
-Much of Otto is built in
-link:https://www.rust-lang.org/[Rust].
-The service-to-service communication is all done with JSON over HTTP.
+Much of Otto is built in link:https://www.rust-lang.org/[Rust]. The project is
+a "cargo workspace" which means that there are multiple binaries and libraries
+defined in the source tree, which can all be built together via the root
+`Cargo.toml`. Much can be accomplished with `cargo build` and `cargo test`,
+which is easily scoped to a single project via the `-p` flag, for example
+`cargo test -p otto-parser`. There is also a `Makefile` which drives some
+higher-level build system behavior.
 
-In order to contribute to the project, please join us on IRC or open pull
-requests and issues.
+Otto is composed of many different services, which communicate via JSON over HTTP.
+
+== Make targets
+
+Running `make` in the root directory will list some brief help output, but some useful make targets to be aware of are documented below:
+
+=== `release`
+
+Build and strip release binaries to prepare for packaging. Most developers
+won't need to execute this target.
+
+=== `run`
+
+Launch the services defined in the `Procfile`. This requires a `cargo build`
+ahead of time, and is really only useful for manual integration testing.
+
+=== `steps`
+
+This target will build and package all the steps defined in `stdlib/`
+
+=== `test`
+
+Runs all the acceptance tests, typically implemented with
+link:https://github.com/kward/shunit2/[shunit2]. This target will *not* run
+`cargo build` or `cargo test`. From a fresh clone, running the acceptance tests
+will require an initial build, for example `cargo build && make test`.
 
 == Subdirectories
 

crates/agent/README.adoc

@@ -0,0 +1,7 @@
+= Otto Agent
+
+**Issue label:** `component/agent`
+
+This directory contains the re-usable code for implementing agents or
+block-scoped steps, essentially all the code necessary for invoking an Otto
+Step Library.

crates/models/README.adoc

@@ -0,0 +1,5 @@
+= Otto Models
+
+This crate is intended to contain very little actual logic, and instead
+contains the definitions for data models which must be serialized and
+deserialized between services in Otto.

crates/parser/README.adoc

@@ -1,6 +1,19 @@
 = Otto Parser
 
-The Otto Parser service is basically a parser engine that speaks HTTP. In the
-`src/` directory you will find the `.pest` grammar definition which outlines
-the Otto Pipeline syntax.
+**Issue label:** `components/parser`
 
+The Otto Parser is a link:https://pest.rs/[Pest] based parser which takes the
+Otto pipeline syntax and converts it into the Otto intermediate pipeline
+representation.
+
+In the `src/` directory you will find the `.pest` grammar definition which
+outlines the currently supported Otto Pipeline syntax.
+
+== Tests
+
+There are unit tests defined in `.rs` files inside of `src/`.
+
+The `test_data/` directory has two directories: `invalid` and `valid`. These
+files are used to validate basic parsing of the Otto pipeline syntax. No other
+validation is done on these files other than ensuring that they parse
+(`valid/`) or that they do not parse (`invalid/`).