1 files changed, 63 insertions, 1 deletions
diff --git a/README.md b/README.md
index 810790c..a59958b 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# `bzipper`
+# bzipper
 
 [`bzipper`](https://crates.io/crates/bzipper) is a binary (de)serialiser for the Rust language.
 
@@ -8,6 +8,7 @@ Therefore, this crate may be more suited for networking or other cases where a f
 Keep in mind that this project is still work-in-progress.
 
 This crate does not require any dependencies at the moment.
+It is also compatible with `no_std`.
 
 See [Docs.rs](https://docs.rs/bzipper/latest/bzipper/) for documentation.
 
@@ -20,6 +21,67 @@ Unsized types, such as `str` and slices, are not supported.
 Instead, array should be used.
 For strings, the `FixedString` type is also provided.
 
+## Usage
+
+This crate revolves around the `Serialise` and `Deserialise` traits, both of which work around streams (more specifically, d-streams and s-streams).
+
+Many core types come implemented with `bzipper`, including primitives as well as some standard library types such as `Option` and `Result`.
+
+### Serialisation
+
+To serialise an object implementing `Serialise`, simply allocate a so-called "s-stream" (short for *serialisation stream*) with the `Sstream` type:
+
+```rs
+let mut buf: [u8; 16] = Default::default();
+
+let mut stream = bzipper::Sstream::new(&mut buf);
+```
+
+The resulting stream is immutable in the sense that it cannot grow its buffer, altough it does keep track of the buffer's state.
+
+A byte sequence can be added to our new stream by passing the stream to a call to the `serialise` method:
+
+```rs
+use bzipper::Serialise;
+
+let mut buf: [u8; 2] = Default::default();
+let mut stream = bzipper::Sstream::new(&mut buf);
+
+0x4554_u16.serialise(&mut stream).unwrap();
+```
+
+The ammount of bytes used by the serialiser (that is, the ammount of bytes written to the stream) is indicated by its return value (i.e. it has the type `Result<usize, Serialise::Error>`).
+
+Whilst the *maximum* ammount of bytes is specified by the `SERIALISE_LIMIT` constant, this can in cases be lower (for example with `None` variants which are always encoded as a single, null byte).
+
+When serialising primitives, the resulting byte stream is in big endian (a.k.a. network endian).
+It is recommended for implementors to adhere to this convention as well.
+
+After serialisation, the s-stream records the new write-to position of the buffer. This allows for *chaining* of serialisations, which can prove useful when implementing the trait for custom types.
+
+### Deserialisation
+
+As with serialisation, deserialisation uses streams (just with the `Dstream` type; short for *deserialisation stream*):
+
+```rs
+let data = [0x45, 0x54];
+
+let mut stream = bzipper::Dstream::new(&data);
+```
+
+Using these streams is also just as simple as with s-streams:
+
+```rs
+use bzipper::Deserialise;
+
+let data = [0x45, 0x54];
+let mut stream = bzipper::Dstream::new(&data);
+
+assert_eq!(u16::deserialise(&mut stream).unwrap(), 0x4554);
+```
+
+When chaining serialisations, keep in mind that appropriate deserialisations should come in **reverse order** (streams function similarly to stacks in this sense).
+
 ## Copyright & Licensing
 
 Copyright 2024 Gabriel Bjørnager Jensen.