Making docs more clearer

[Sameer2307]

[freeranger]

Unfortunately some of the acceptance tests fail - which should not be affected by this PR so I guess other factors are at play, perhaps some incompatibility Sonar introduced in one of their recent releases. I will leave it for @jdamata to decide if he wants to merge this change (and probably have the tests fail on the main branch too) or look into the failing tests and address them first.

One of the downsides of non-deterministic testing is that the tests can fail on a PR because of some environment or other change outside the developers control....