Document the whys and knobs

[tarsius]

Explain the reasoning behind important design decisions. In the same document also describe the configuration options that users can use to make things behave more like they expected.