From 9c0cf07bcc5227dfc8b95106c28bd8e16ed22ed6 Mon Sep 17 00:00:00 2001
From: Paul Campbell <pcampbell@kemitix.net>
Date: Fri, 8 Nov 2024 19:46:19 +0000
Subject: [PATCH] docs(readme): write a proper readme

---
 README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 64 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 92c4436..e69904e 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,69 @@
-## kxio
+# kxio
 
-Provides injectable Filesystem and Network resources to make code more testable.
+`kxio` is a Rust library that provides injectable `FileSystem` and `Network`
+resources to enhance the testability of your code. By abstracting system-level
+interactions, `kxio` enables easier mocking and testing of code that relies on
+file system and network operations.
 
-### Filesystem
+## Features
 
-Documentation is [here](https://docs.rs/kxio/latest/kxio/fs/).
+- **Filesystem Abstraction**
+- **Network Abstraction**
+- **Enhanced Testability**
 
-### Network
+## Filesystem
+
+The Filesystem module offers a clean abstraction over `std::fs`, the standard
+file system operations. For comprehensive documentation and usage examples,
+please refer to the <https://docs.rs/kxio/latest/kxio/fs/>.
+
+### Key Filesystem Features:
+
+- File reading and writing
+- Directory operations
+- File metadata access
+- Fluent API for operations like `.reader().bytes()`
+
+## Network
+
+The Network module offers a testable interface over the `reqwest` crate. For
+comprehensive documentation and usage examples, please refer to
+<https://docs.rs/kxio/latest/kxio/net/>
+
+## Getting Started
+
+Add `kxio` to your `Cargo.toml`:
+
+```toml
+[dependencies]
+kxio = "x.y.z"
+```
+
+## Usage
+
+See the example [get.rs](./examples/get.rs) for an annotated example on how to use the `kxio` library.
+It covers both the `net` and `fs` modules.
+
+## Development
+
+- The project uses [Cargo Mutants](https://crates.io/crates/cargo-mutants) for mutation testing.
+- [ForgeJo Actions](https://forgejo.org/docs/next/user/actions/) are used for continuous testing and linting.
+
+## Contributing
+
+Contributions are welcome! Please check our [issue tracker](https://git.kemitix.net/kemitix/kxio/issues) for open tasks or
+submit your own ideas.
+
+## License
+
+This project is licensed under the terms specified in the `LICENSE` file in the
+repository root.
+
+## Acknowledgements
+
+- Built with Rust
+
+---
+
+For more information, bug reports, or feature requests, please visit our [repository](https://git.kemitix.net/kemitix/kxio).
 
-The entire [network] module needs to be completly rewritten
-It's use is strongly discouraged.
-A new [net] module will likely be its replacement.