1 files changed, 34 insertions, 12 deletions
diff --git a/README.md b/README.md
index 98ed818..218a4fd 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,48 @@
 # gleam_json
 
-A Gleam program
+A Gleam library for encoding decoding JSON.
 
+### Encoding
 
-## Quick start
+```rust
+import gleam/json
 
-```sh
-# Build the project
-rebar3 compile
+let data = json.object([
+  tuple("foo", json.string("bar")),
+  tuple("values", json.list([json.int(1), json.int(2)])),
+  tuple("nope", json.null())
+])
+json.encode(data)
+// {"foo":"bar","nope":null,"values":[1,2]}
+```
 
-# Run the eunit tests
-rebar3 eunit
+### Decoding
 
-# Run the Erlang REPL
-rebar3 shell
-```
+Note: JSON is a dynamic data structure.
+The best way to manage decode JSON data is using `gleam/dynamic`.
+
+```rust
+import gleam/json
+
+let encoded =
+  "{\"foo\":\"bar\",\"nope\":null,\"values\":[1,2]}"
 
+assert Ok(data) = json.decode(encoded)
+let data = dynamic.from(data)
+
+assert Ok(foo) = dynamic.field(data, "foo")
+assert Ok("bar") = dynamic.string(foo)
+
+assert Ok(values) = dynamic.field(data, "values")
+assert Ok([1, 2]) = dynamic.typed_list(values, dynamic.int)
+
+assert Ok(nope) = dynamic.field(data, "nope")
+assert Ok(_) = dynamic.atom(nope)
+```
 
 ## Installation
 
-If [available in Hex](https://www.rebar3.org/docs/dependencies#section-declaring-dependencies)
-this package can be installed by adding `gleam_json` to your `rebar.config` dependencies:
+This package can be installed by adding `gleam_json` to your `rebar.config` dependencies:
 
 ```erlang
 {deps, [