diff --git a/README.md b/README.md
index f4fd9be..cdba93f 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,7 @@
 
 **fatamorgana** is a Python package for reading and writing OASIS format layout files.
 
+**Homepage:** https://mpxd.net/gogs/jan/fatamorgana
 
 **Capabilities:**
 * This package is a work-in-progress and is largely untested -- it works for
@@ -23,7 +24,7 @@
 * (optional) numpy
 
 
-Install with pip from PyPi:
+Install with pip from PyPi (preferred):
 ```bash
 pip install fatamorgana
 ```
@@ -33,6 +34,26 @@ Install directly from git repository:
 pip install git+https://mpxd.net/gogs/jan/fatamorgana.git@release
 ```
 
-## Use
+## Documentation
+Most functions and classes are documented inline.
+
+To read the inline help,
+```python3
+import fatamorgana
+help(fatamorgana.OasisLayout)
+```
+The documentation is currently very sparse and I expect to improve it whenever possible!
 
 
+## Examples
+
+Read an OASIS file and write it back out:
+```python3
+    import fatamorgana
+
+    with open('test.oas', 'rb') as f:
+        layout = fatamorgana.OasisLayout.read(f)
+    
+    with open('test_write.oas', 'wb') as f:
+        layout.write(f)
+```