3 files changed, 37 insertions, 83 deletions

diff --git a/fondant_deps/readme.md b/fondant_deps/readme.md
index 15926e3..3366f48 120000..100644
--- a/fondant_deps/readme.md
+++ b/fondant_deps/readme.md
@@ -1 +1,3 @@
-../readme.md
\ No newline at end of file
+### fondant_deps
+
+> external crates and utils that `fondant` requires
diff --git a/fondant_derive/readme.md b/fondant_derive/readme.md
index 15926e3..0e32c0d 120000..100644
--- a/fondant_derive/readme.md
+++ b/fondant_derive/readme.md
@@ -1 +1,3 @@
-../readme.md
\ No newline at end of file
+### fondant_derive
+
+> core macro definitions
diff --git a/readme.md b/readme.md
index f76f63c..753faba 100644
--- a/readme.md
+++ b/readme.md
@@ -1,10 +1,16 @@
 # fondant
 
+[Documentation](https://docs.rs/fondant/) ·
 [Architecture](#Architecture) · [Usage](#Usage) ·
 [Customization](#Customization) · [Todo](#Todo)
 
 `fondant` is a macro based library to take the boilerplate out of
-configuration handling. Most of `fondant` is based off the `confy` crate.
+configuration handling. All you need to do is derive the
+`Configure` trait on your struct, and fondant will decide
+where to store it and and how to do so safely.
+
+
+Most of `fondant` is based off the `confy` crate.
 
 `fondant` adds a couple of extra features:
 
@@ -12,117 +18,61 @@ configuration handling. Most of `fondant` is based off the `confy` crate.
  - support for custom config paths
  - support for custom config file names
 
-### Architecture
-
-`fondant` is split into 3 separate crates:
+### Usage ([Full Documentation](https://docs.rs/fondant/))
 
- - `fondant_deps`: external crates and utils that `fondant` requires
- - `fondant_derive`: core macro definitions
- - `fondant`: the user facing library that brings it all together
+Drop this in your `Cargo.toml` to gets started:
 
-This slightly strange architecture arose because of some
-limitations with proc-macro crates and strict cyclic
-dependencies in cargo. All you need is the `fondant` crate.
+```
+[dependencies]
+fondant = "0.1.0"
+```
 
-### Usage
+Derive the macro:
 
 ```rust
 // the struct has to derive Serialize, Deserialize and Default
+use fondant::Configure;
+use serde::{Serialize, Deserialize};
+
 #[derive(Configure, Serialize, Deserialize, Default)]
 #[config_file = "config.toml"]
-// |
-// `-- this attribute sets the file name to "config.toml"
-// `-- the file format to "toml"
-// `-- the file path to "default" (read the notes below)
 struct AppConfig {
-    version: u32,
     port: u32,
     username: String,
 }
 
 fn main() {
-    // use `load` (associated method) to load the config file
+    // use `load` to load the config file
+    // loads in Default::default if it can't find one
     let mut conf = AppConfig::load().unwrap();
 
     // do stuff with conf
-    conf.version = 2;
+    conf.port = 7878;
 
     // call `store` to save changes
     conf.store().unwrap();
 }
 ```
 
-**Notes**:  
- - `load` returns `Default::default` if the config file is not present, and stores
- a serialized `Default::default` at the specified path
- - the "default" config path varies by platform:
-    * GNU/Linux: `$XDG_CONFIG_HOME/my_cool_crate/config.toml` (follows xdg spec)
-    * MacOS: `$HOME/Library/Preferences/my_cool_crate/config.toml`
-    * Windows: `{FOLDERID_RoamingAppData}\_project_path_\config`
-
-### Customization
-
-Set your own filename, for ex.: `apprc`
-
-```rust
-#[derive(Configure, Serialize, Deserialize, Default)]
-#[config_file = "apprc.toml"]
-struct AppConfig {
-    // -- snip --
-}
-// effective path: $XDG_CONFIG_HOME/my_cool_crate/apprc.toml
-// effective format: toml
-```
-
-Change file format to `yaml`, by changing the file extension.
-Supported extensions are `yaml`, `toml`, `json`:
-
-```rust
-#[derive(Configure, Serialize, Deserialize, Default)]
-#[config_file = "config.yaml"]
-struct AppConfig {
-    // -- snip --
-}
-// effective path: $XDG_CONFIG_HOME/my_cool_crate/config.yaml
-// effective format: yaml
-```
+Find more examples and options at [docs.rs](https://docs.rs/fondant/).
 
-Override the default config path, for ex.: the home directory
-(it is not recommended to override config path):
+### Architecture
 
-```rust
-#[derive(Configure, Serialize, Deserialize, Default)]
-#[config_file = "~/.apprc.json"]
-struct AppConfig {
-    // -- snip --
-}
-// effective path: $HOME/.apprc.json
-// effective format: json
-```
+`fondant` is split into 3 separate crates:
 
-Fondant meshes well with Serde, for ex.:
-```rust
-#[derive(Configure, Serialize, Deserialize, Default)]
-#[config_file = "config.toml"]
-struct Madagascar {
-    #[serde(skip)]
-    rating: u32,
+ - `fondant_deps`: external crates and utils that `fondant` requires
+ - `fondant_derive`: core macro definitions
+ - `fondant`: the user facing library that brings it all together
 
-    name: String,
-    penguins: u32,
-}
-```
+This slightly strange architecture arose because of some
+limitations with proc-macro crates and strict cyclic
+dependencies in cargo. All you need is the `fondant` crate.
 
-Above snippet produces this config file:
-```toml
-name = 'Central Park Zoo'
-penguins = 4
-```
 
 ### Todo
 
- - [ ] improve error from trait impl
+ - [ ] improve error types
  - [ ] use `syn::Error` and `syn::Result` to report macro errors
  - [x] write docs
- - [ ] bundle and publish to crates.io
+ - [x] bundle and publish to crates.io