bloomreach / docs-feedback

1 stars 0 forks source link

may or must? Use clear and consistent language. #99

Closed JasperFloorBloomreach closed 2 years ago

JasperFloorBloomreach commented 2 years ago

https://xmdocumentation.bloomreach.com/library/upgrade-14-to-15/steps/rename-culturally-insensitive-terms.html

In the upgrade notes it mentions the change the usage of white/black to allow/block. For many of the items the wording is such that the rename is required, but two items leave this in doubt.

This implies that it is optional.

This is not optional in the text, but the text will be easy to confuse. Use clear language.

The other items use the following wording:

So there is one use of the same wording, but in general each item finds a new way to say the same thing. While stylistically one might argue repeating the same wording is ugly, in this case it is technical instructions not literature. The wording should be equivalent and it should be clear if something is or isn't optional.

nvankampenhout commented 2 years ago

I agree and have changed them all to "must be renamed".