Better document decisions and examples

[lanthaler]

The spec is completely outdated and not a good way to document progress. It was thus decided to create a more lightweight documentation similar to the use case documents.

There's an initial action item on Tomasz to come up with a rough structure of how the documentation should look like

/cc @tpluscode