diff --git a/README.md b/README.md
index abe2190..db8e427 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,8 @@
 
 ## Usage
 
+### Example
+
 Say you have a TOML file that looks like this:
 
 ```toml
@@ -46,6 +48,28 @@
 }
 ```
 
+### Dealing with values
+
+Here are some important functions you need to know in order to work with the
+values in a TOML tree:
+
+* `tree.Get("comma.separated.path")` Returns the value at the given path in the
+  tree as an `interface{}`. It's up to you to cast the result into the right
+  type.
+* `tree.Set("comma.separated.path", value)` Sets the value at the given path in
+  the tree, creating all necessary intermediate subtrees.
+
+### Dealing with positions
+
+Since
+[e118479061](https://github.com/pelletier/go-toml/commit/e1184790610b20d0541fc9f57c181cc5b1fc78be),
+go-toml supports positions. This feature allows you to track the positions of
+the values inside the source document, for example to provide better feedback in
+your application. Using positions works much like values:
+
+* `tree.GetPosition("comma.separated.path")` Returns the position of the given
+  path in the source.
+
 ## Documentation
 
 The documentation is available at