Improve documentation

[kopf]

Improve documentation such that:

• we begin by defining a simple API and use it for all examples
• the explanation of the conditions is less technical