Revamp documentation

[balopat]

The docs need a bit more love.
This is an overarching issue that would be done when a more extensive documentation is done.

• Get to an agreement on tooling
• Get agreed on an outline
• document all the outstanding docs issues
• implement all the individual parts of the outline

The main goal is to get to a place where all features and knobs are well described, after which, we can enforce a contributor policy that adding a contribution would only considered done if there is a corresponding change in documentation and the annotated skaffold.yaml.