update documentation section according to our discusscion about "docs-as-code"

we want to merge the outcome of our discussion into our chapter about documentation