From 186fab5a68fbe17e9a2a605fb46bf996f0babf27 Mon Sep 17 00:00:00 2001
From: Yuval Adam <_@yuv.al>
Date: Thu, 23 May 2024 11:08:35 +0200
Subject: Cleanup and clarify README

---
 README.md | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index f0e14aa..0d21fb8 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,10 @@
 
 A simple ORM-like utility for operating on local YAML files via Python dataclasses.
 
+In the context of this library, a *stash* is a diretory in the filesystem that holds many `.yml` files that all adhere to the same structure.
+
+`ymlstash` simplifies the management of such a basic database of files.
+
 ## Install
 
 Package is published on PyPI - https://pypi.org/project/ymlstash/
@@ -14,7 +18,7 @@ $ pip install ymlstash
 
 ## Usage
 
-Define a dataclass:
+Start by defining your model as a dataclass:
 
 ```python
 from dataclasses import dataclass
@@ -28,7 +32,13 @@ class User:
     key: ClassVar[str] = "name"
 ```
 
-Note the special `key` field which is used to denote that `name` should be used as the primary key field. If an object has `name: "foo"`, it will be saved as `foo.yml` in the stash root directory.
+### Primary Keys
+
+Each model **must** include a primary key that will be used as the entry filename to uniquely access each record. 
+
+The recommended way do to this is with the special `key` field which is used to denote that `name` should be used as the primary key field. If an object has `name: "foo"`, it will be saved as `foo.yml` in the stash root directory.
+
+### Actions
 
 Instantiate a new object:
 
@@ -41,13 +51,13 @@ Save it to file:
 ```python
 from ymlstash import YmlStash
 
-stash = YmlStash(User, "path/to/db")
+stash = YmlStash(User, "path/to/db")  # path can either be a string or Path() object
 stash.save(user)
 ```
 
 This will create a `yuval.yml` file in the stash root directory.
 
-When saving to file, a `key` field must be present on the dataclass, otherwise an explicit `key` must be passed:
+If the `key` field is not present on the dataclass, an explicit `key` must be passed:
 
 ```python
 stash.save(obj, key="custom-key")
@@ -71,7 +81,7 @@ Delete a key:
 stash.delete("foo")
 ```
 
-Check for key existance:
+Check for key existence:
 
 ```python
 stash.exists("foo")
-- 
cgit v1.3.1