opinionated changes to the README

README.md

@@ -1,31 +1,42 @@
 # peach-devdocs
 
-Developer documentation for PeachCloud in the form of a Markdown book.
+Developer documentation for [PeachCloud](https://github.com/peachcloud) in the form of a Markdown book.
 
-_Note: the book is not yet available in built-form online. A link will be included in this repo when that is the case._
+:book: Read this online [**here**](./src/README.md)
 
-### Quickstart
+:construction: _TODO - publish this online somewhere!_ :construction:
 
-If you do not wish to build and serve the book locally, simply navigate to the [src/SUMMARY.md](https://github.com/peachcloud/peach-devdocs/blob/master/src/SUMMARY.md) file on the GitHub repo and read the documentation from there.
+## Development
 
-### Setup
+Dependencies:
+- [mdBook](https://github.com/rust-lang/mdBook) (release binaries or cargo install)
 
-[mdBook](https://github.com/rust-lang/mdBook) is required to build and serve the book locally. Installation can be achieved via the [release binaries](https://github.com/rust-lang/mdBook/releases) or directly via Cargo (assuming you have Rust version 1.35 or higher and Cargo installed):
+```bash
+$ git clone https://github.com/peachcloud/peach-devdocs
+$ cd peach-devdocs
+$ mdbook serve
+```
 
-`cargo install mdbook`
+This serves the current state of the book at [localhost:3000](http://localhost:3000).
+When changes to any files are saved, the browser view will automatically refresh to reflect the new state.
 
-Once mdBook is installed, clone this repo:
+**NOTES**:
+- this assumes `mdbook` is in you `PATH`
+  - the command for adding the default cargo bin directory is `export PATH=$PATH:~/.cargo/bin`.
+  - if you downloaded the prebuilt binary then make sure the directory it's in is in your `PATH`
 
-`git clone https://github.com/peachcloud/peach-devdocs`
 
-Move into the repo, add the Cargo bin directory to your `PATH`, build and serve:
+## Build a release
 
-`cd peach-devdocs`  
+```
-`export PATH=$PATH:~/.cargo/bin`  
+$ mdbook serve
-`mdbook build`  
+```
-`mdbook serve`
+
+This builds the book into a static release ready for publishing.
+Currently outputs to `book/` directory.
+
+:construction: _TODO - describe how and where this is published / hosted_ :construction:
 
-The book is served on `localhost:3000` by default and refreshes automatically in-browser when changes to the documentation are saved.
 
 ### Licensing