diff --git a/README.md b/README.md
index a5ac46d..ebf80c5 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,57 @@ A Clojure library designed to provide simple interationalisation of user-facing
 
 ## Usage
 
+To use this library in your project, add the following leiningen dependency:
 
+    [org.clojars.simon_brooke/internationalisation "1.0.0"]
+
+To use it in your namespace, require:
+
+    [scot.weft.i18n.core :refer [get-messages]]
+
+There is only one function you should need to use:
+
+### get-messages
+
+    (get-messages accept-language-header resource-path default-locale)
+
+Return the most acceptable messages collection we have given this accept-language-header. Do not use this function directly, use the memoized variant get-messages, as performance will be very much better.
+
+* `accept-language-header` should be the value of an RFC 2616 Accept-Language header;
+* `resource-path` should be the fully-qualified path name of the directory in which message files are stored;
+* `default-locale` should be a locale specifier to use if no acceptable locale can be identified.
+
+Returns a map of message keys to strings.
+
+See [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt).
+
+## The translation files
+
+Obviously, this only works if you provide files with translations of your interesting strings. These files should contain Clojure maps, and the file names should be the locale string for which the file is relevent followed by the extension ".edn". All the translation files should be in the same directory.
+
+In this project you will find two very simple example files, which should give you the idea:
+
+### en-GB.edn
+
+```
+;;;; This is a British English translation file.
+
+{:pipe "This is not a pipe"}
+```
+
+### fr-FR.edn
+
+```
+;;;; This is a French translation file.
+
+{:pipe "Ceci n'est pas une pipe."}
+```
+
+## Documentation
+
+Documentation may be generated by running
+
+    lein codox
 
 ## License
 
diff --git a/doc/intro.md b/doc/intro.md
index 39a4182..732bd13 100644
--- a/doc/intro.md
+++ b/doc/intro.md
@@ -1,3 +1,62 @@
 # Introduction to internationalisation
 
-TODO: write [great documentation](http://jacobian.org/writing/what-to-write/)
+## Usage
+
+To use this library in your project, add the following leiningen dependency:
+
+    [org.clojars.simon_brooke/internationalisation "1.0.0"]
+
+To use it in your namespace, require:
+
+    [scot.weft.i18n.core :refer [get-messages]]
+
+There is only one function you should need to use:
+
+### get-messages
+
+    (get-messages accept-language-header resource-path default-locale)
+
+Return the most acceptable messages collection we have given this accept-language-header. Do not use this function directly, use the memoized variant get-messages, as performance will be very much better.
+
+* `accept-language-header` should be the value of an RFC 2616 Accept-Language header;
+* `resource-path` should be the fully-qualified path name of the directory in which message files are stored;
+* `default-locale` should be a locale specifier to use if no acceptable locale can be identified.
+
+Returns a map of message keys to strings.
+
+See [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt).
+
+## The translation files
+
+Obviously, this only works if you provide files with translations of your interesting strings. These files should contain Clojure maps, and the file names should be the locale string for which the file is relevent followed by the extension ".edn". All the translation files should be in the same directory.
+
+In this project you will find two very simple example files, which should give you the idea:
+
+### en-GB.edn
+
+```
+;;;; This is a British English translation file.
+
+{:pipe "This is not a pipe"}
+```
+
+### fr-FR.edn
+
+```
+;;;; This is a French translation file.
+
+{:pipe "Ceci n'est pas une pipe."}
+```
+
+## Documentation
+
+Documentation may be generated by running
+
+    lein codox
+
+## License
+
+Copyright © 2017 Simon Brooke
+
+Distributed under the Eclipse Public License either version 1.0 or (at
+your option) any later version.
diff --git a/project.clj b/project.clj
index 64b1026..205932d 100644
--- a/project.clj
+++ b/project.clj
@@ -1,7 +1,9 @@
-(defproject org.clojars.simon_brooke/internationalisation "0.1.0-SNAPSHOT"
+(defproject org.clojars.simon_brooke/internationalisation "1.0.0"
   :description "Internationalisation library for Clojure"
   :url "https://github.com/simon-brooke/internationalisation"
   :license {:name "Eclipse Public License"
             :url "http://www.eclipse.org/legal/epl-v10.html"}
   :dependencies [[org.clojure/clojure "1.7.0"]
-                 [instaparse "1.4.7"]])
+                 [com.taoensso/timbre "4.10.0"]
+                 [instaparse "1.4.7"]]
+  :plugins [[lein-codox "0.10.3"]])
diff --git a/resources/i18n/en-GB.edn b/resources/i18n/en-GB.edn
index c6da5bb..3d1133c 100644
--- a/resources/i18n/en-GB.edn
+++ b/resources/i18n/en-GB.edn
@@ -1 +1,3 @@
+;;;; This is a British English translation file.
+
 {:pipe "This is not a pipe"}
diff --git a/resources/i18n/fr-FR.edn b/resources/i18n/fr-FR.edn
index 8f8e130..c110396 100644
--- a/resources/i18n/fr-FR.edn
+++ b/resources/i18n/fr-FR.edn
@@ -1 +1,3 @@
+;;;; This is a French translation file.
+
 {:pipe "Ceci n'est pas une pipe."}
diff --git a/src/scot/weft/i18n/core.clj b/src/scot/weft/i18n/core.clj
index e40a907..b0df4e8 100644
--- a/src/scot/weft/i18n/core.clj
+++ b/src/scot/weft/i18n/core.clj
@@ -3,7 +3,8 @@
   scot.weft.i18n.core
   (:require [clojure.string :as cs]
             [clojure.java.io :as io]
-            [instaparse.core :as insta]))
+            [instaparse.core :as insta]
+            [taoensso.timbre :as timbre]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
@@ -40,6 +41,7 @@
   "From a `parse-tree` generated by the `language-specifier-grammar`, generate
   a list of maps each having a `:language` key, a `:preference` key and a
   `:qualifier` key."
+  {:doc/format :markdown}
   [parse-tree]
   (if
     (nil? parse-tree)
@@ -86,6 +88,7 @@
 
   Returns a list of maps as generated by `generate-accept-languages`, in descending order
   of preference."
+  {:doc/format :markdown}
   [accept-language-header]
   (reverse
     (sort-by
@@ -103,6 +106,7 @@
   message files are stored.
 
   Returns the name of an appropriate file if any is found, else nil."
+  {:doc/format :markdown}
   [language-spec resource-path]
   (cond
     (and
@@ -131,17 +135,20 @@
   identified.
 
   Returns a map of message keys to strings."
+  {:doc/format :markdown}
   [accept-language-header resource-path default-locale]
-  (read-string
-    (slurp
-      (or
-        (first
-          (remove
-            nil?
-            (map
-              #(find-language-file-name % resource-path)
-              (acceptable-languages accept-language-header))))
-        (str resource-path default-locale ".edn")))))
+  (let [file-path (first
+                    (remove
+                      nil?
+                      (map
+                        #(find-language-file-name % resource-path)
+                        (acceptable-languages accept-language-header))))]
+    (timbre/debug (str "Found i18n file at '" file-path "'"))
+    (read-string
+      (slurp
+        (or
+          file-path
+          (str resource-path default-locale ".edn"))))))
 
 
 (def get-messages