Clarification detective doc

nico requested to merge fix/clearer_detective_doc into future/release-1.9 Jul 26, 2021