Update README.md

README.md

@@ -1,3 +1,36 @@
 # alembic-data
 
-Data Migrations for Alembic/SQLAlchemy.
+Data Migrations for Alembic/SQLAlchemy.
+
+## State of this Project
+
+This project was originally written as part of Karman but then abandoned in the process of migrating to non-relational databases. No further development will be done.
+
+## Usage
+
+When declaring models you can register specific object instances to be created during migrations. Currently the detection of changes is very rudimentary.
+
+```python
+from alembic_data import *
+
+class Model:
+  ...
+
+register_object(Model(...))
+register_object(Model(...))
+```
+
+Alternatively you can declare a model as a *managed model*. A managed model’s instances will be exclusively created by alembic-data. This is probably the most useful application. This way alembic-data can make sure that only objects created via `register_object` will exist in the database.
+
+```python
+from alembic_data import *
+
+@managed_model
+class Model:
+  ...
+
+register_object(Model(...))
+register_object(Model(...))
+# There will only be 2 instances of Model
+```
+