diff --git a/README.md b/README.md
index 6a1eafa..d59220a 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,53 @@
 # Simple-File-Settings
 
-This is a package intended to easily load and save simple configuration data
-transparently through a class.
+[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![GitHub license](https://img.shields.io/github/license/NathanVaughn/simple-file-settings)](https://github.com/NathanVaughn/simple-file-settings/blob/main/LICENSE)
+[![PyPi versions](https://img.shields.io/pypi/pyversions/simple-file-settings)](https://pypi.org/project/simple-file-settings)
+[![PyPi downloads](https://img.shields.io/pypi/dm/simple-file-settings)](https://pypi.org/project/simple-file-settings)
+
+---
+
+Sometimes, you just need to save and retain a few settings for your desktop program,
+like a theme preference, or last viewed directory. This is a library intended to easily
+load and save simple configuration data to and from disk through a
+type-checked data class.
 
 ## Usage
 
+First, a basic use case:
+
+```bash
+pip install simple-file-settings
+```
+
+```python
+import os
+from simplefilesettings.json import JSONClass
+
+class _Settings(JSONClass):
+    class Config:
+        json_file = os.path.join(os.path.expanduser("~"), "config.json")
+
+    mqtt_host: str = "mqtt"
+    mqtt_port: int = 1883
+    serial_port: str = "COM1"
+    serial_baud_rate: int = 115200
+    log_file_directory: str = os.path.join(os.getcwd(), "logs")
+    force_light_mode: bool = False
+    joystick_inverted: bool = False
+    max_moving_map_tracks: int = 5000
+    takeoff_height: float = 3
+
+Settings = _Settings()
+
+# this will attempt to load the value from the file on disk, or revert to the default
+print(Settings.serial_port)
+
+# this will save the change to the config file
+Settings.serial_port = "/dev/tty1"
+```
+
 Inherit `simplefilesettings.json.JSONClass` and add class attributes with
 type hints and default values. Attributes without type hints will not be
 loaded or saved. Attributes without a default value, or starting with an
@@ -34,12 +77,12 @@ class _Settings(JSONClass):
     name: str = "John"
 ```
 
-Nested classes are not supported.
+Data types not JSON serializable (objects, datetimes, etc.) are not supported.
 
-By default, when any attribute is accessed, the configured file will be read. If the file
-does not exist, the default value will be used. If the file is not valid JSON,
-it will be deleted automatically. To only read the file one time, set the `Config`
-value `always_read` to `False`.
+By default, when any attribute is accessed, the configured file will be read.
+If the file does not exist, the default value will be used.
+If the file is not valid JSON, it will be deleted automatically.
+To only read the file one time, set the `Config` value `always_read` to `False`.
 
 When any attribute has its value set, that will be written to the configured file.
 
@@ -83,7 +126,7 @@ class _YSettings(YAMLClass):
 python -m pip install pipx --upgrade
 pipx ensurepath
 pipx install poetry
-pipx install vscode-task-runner
+pipx install simple-file-settings
 # (Optionally) Add pre-commit plugin
 poetry self add poetry-pre-commit-plugin
 ```