Write documentation

[smichel17]

• Document public API
• Add usage example(s). Having this in the readme would be fine, but better would be a small sample app that implements a simple transition — this forces us to keep the example up to date.