Improve documentation and add HCL examples

[adambarreiro]

This PR does two things:

• Reorganises and improves the markdown documents present in this repo.
• Adds HCL examples to help customers to use the provider

Also improves some leftovers in vcfa_supervisor_namespace

[tenthirtyam]

@adambarreiro @Didainius and #lvirbalas,

Might I suggest including the following for a better docs experience:

git mv TESTING.md docs/testing.md
git mv TROUBLESHOOTING.md docs/troubleshooting.md
git mv CODING_GUIDELINES.md docs/coding-guidelines.md

[Didainius]

Created and destroyed the provided example from scratch - it worked.

[lvirbalas]

Suggesting improvements in-line.

[lvirbalas]

Great to have these examples here! Thanks!

[adambarreiro]

@adambarreiro @Didainius and #lvirbalas,

Might I suggest including the following for a better docs experience:

git mv TESTING.md docs/testing.md
git mv TROUBLESHOOTING.md docs/troubleshooting.md
git mv CODING_GUIDELINES.md docs/coding-guidelines.md

Hi Ryan, after discussing we kind of reverted, just to have a clear separation between "user-facing docs" in docs and "developer-facing docs" in the root directory, where any potential contributor can easily find them.

As per the README.md, I improved it with the badges and a bit of cleanup.

Thanks for the suggestions!