The problem, IMHO, is that no one reads until the end of the sentence for the example. When I got this error, I read the comment again but never made it till the end. I then just went to search and found this issue.
Also, it is worth considering that most use cases for placeholders will be to use in paths like user/%/... or node/%/.... It would be worth bringing up the named parameters earlier.
How about something like this?
This view will be displayed by visiting this path on your site. You may use "%" or named route parameters like "%node" in your URL to represent values that will be used for contextual filters: For example, "node/%node/feed" or "view_path/%". The named route parameters are necessary when used within paths used by entities such as "taxonomy/term/%taxonomy_term" or "user/%user/custom-view"
Attaching a patch with above.