diff --git a/README.md b/README.md
index dfd3711..b9d53ce 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,45 @@
 # golang-directories
 
-Golang implementation of https://lib.rs/crates/directories
\ No newline at end of file
+Golang implementation of https://lib.rs/crates/directories
+
+Per-user/per-application WRITEABLE paths for cross-platform idiomatic locations.
+
+Currently supports Linux, Windows and mac.  Future additions: iOS,Android, plan9?
+
+All functions have the same signature :
+```
+function user.Fonts() (string, error)
+```
+and return an Error if they cannot satisfy the request on a particular platform (e.g. Windows doesn't have a per-user font directory)
+
+You need to set your project details before using the functions in `golang-directories/project` by calling project.SetProjectName
+
+`"git.martyn.berlin/martyn/golang-directories/base"` contains :
+* `Home()`
+* `Cache()`
+* `Config()`
+* `Data()`
+* `DataLocal()`
+* `Executable()`
+* `Preferences()`
+* `Runtime()`
+* `State()`
+
+`"git.martyn.berlin/martyn/golang-directories/user"` contains :
+* `Home()`
+* `Audio()`
+* `Desktop()`
+* `Documents()`
+* `Downloads()`
+* `Fonts()`
+* `Pictures()`
+* `Public()`
+* `Templates()`
+* `Videos()`
+
+and `"git.martyn.berlin/martyn/golang-directories/project"` alongside `SetProjectName()` contains :
+* `Cache()`
+* `Config()`
+* `Data()`
+* `DataLocal()`
+* `Preferences()`
\ No newline at end of file