Document use cases

Closes #126

.vscode/settings.json

@@ -20,5 +20,12 @@
   "python.linting.pylintArgs": ["--rcfile", ".pylint.ini"],
   "python.linting.mypyEnabled": true,
   "python.linting.mypyArgs": ["--config-file", ".mypy.ini"],
-  "python.linting.pydocstyleEnabled": true
+  "python.linting.pydocstyleEnabled": true,
+  "cSpell.words": [
+    "backends",
+    "dataclass",
+    "dataclasses",
+    "datafile",
+    "datafiles"
+  ]
 }

Makefile

@@ -103,8 +103,8 @@ $(MKDOCS_INDEX): docs/requirements.txt mkdocs.yml docs/*.md
 docs/requirements.txt: poetry.lock
 	@ poetry run pip freeze -qqq | grep mkdocs > $@
 
-.PHONY: mkdocs-live
-mkdocs-live: mkdocs
+.PHONY: mkdocs-serve
+mkdocs-serve: mkdocs
 	eval "sleep 3; bin/open http://127.0.0.1:8000" &
 	poetry run mkdocs serve
 

README.md

@@ -1,14 +1,21 @@
 # Datafiles: A file-based ORM for dataclasses
 
-Datafiles is a bidirectional serialization library for Python [dataclasses](https://docs.python.org/3/library/dataclasses.html) to synchronizes objects to the filesystem using type annotations. It supports a variety of file formats with round-trip preservation of formatting and comments, where possible. By default, changes are automatically saved and only include the minimum data needed to restore an object.
+Datafiles is a bidirectional serialization library for Python [dataclasses](https://docs.python.org/3/library/dataclasses.html) to synchronizes objects to the filesystem using type annotations. It supports a variety of file formats with round-trip preservation of formatting and comments, where possible. Object changes are automatically saved to disk and only include the minimum data needed to restore each object.
 
 [![PyPI Version](https://img.shields.io/pypi/v/datafiles.svg)](https://pypi.org/project/datafiles)
 [![PyPI License](https://img.shields.io/pypi/l/datafiles.svg)](https://pypi.org/project/datafiles)
 [![Travis CI](https://img.shields.io/travis/jacebrowning/datafiles/develop.svg?label=unix)](https://travis-ci.org/jacebrowning/datafiles)
 [![AppVeyor](https://img.shields.io/appveyor/ci/jacebrowning/datafiles/develop.svg?label=windows)](https://ci.appveyor.com/project/jacebrowning/datafiles)
 [![Coveralls](https://img.shields.io/coveralls/jacebrowning/datafiles.svg)](https://coveralls.io/r/jacebrowning/datafiles)
 
-## Usage
+Popular use cases include:
+
+- Coercing user-editable files into the proper Python types
+- Storing program configuration and data in version control
+- Loading data fixtures for demonstration or testing purposes
+- Prototyping data models agnostic of persistance backends
+
+## Overview
 
 Take an existing dataclass such as [this example](https://docs.python.org/3/library/dataclasses.html#module-dataclasses) from the documentation:
 

docs/index.md

@@ -1,6 +1,13 @@
 <h1>Datafiles</h1>
 
-Datafiles is a bidirectional serialization library for Python [dataclasses](https://docs.python.org/3/library/dataclasses.html) that automatically synchronizes object instances to the filesystem using type annotations. It supports a variety of file formats with round-trip preservation of formatting and comments, where possible.
+Datafiles is a bidirectional serialization library for Python [dataclasses](https://docs.python.org/3/library/dataclasses.html) to synchronizes objects to the filesystem using type annotations. It supports a variety of file formats with round-trip preservation of formatting and comments, where possible. Object changes are automatically saved to disk and only include the minimum data needed to restore each object.
+
+Popular use cases include:
+
+- Coercing user-editable files into the proper Python types
+- Storing program configuration and data in version control
+- Loading data fixtures for demonstration or testing purposes
+- Prototyping data models agnostic of persistance backends
 
 ## Installation