I would really appreciate it if we can clearly differentiate between hard requirements (e.g. “You must do it this way or it will not work or seriously break”) and recommendations (“It is recommended to do it that way but will still work if you not”).
I suggest to use the keywords MUST, MUST NOT, SHOULD, SHOULD NOT etc. as specified in https://www.ietf.org/rfc/rfc2119.txt:
- MUST This word, or the terms “REQUIRED” or “SHALL”, mean that the
definition is an absolute requirement of the specification.
- MUST NOT This phrase, or the phrase “SHALL NOT”, mean that the
definition is an absolute prohibition of the specification.
- SHOULD This word, or the adjective “RECOMMENDED”, mean that there
may exist valid reasons in particular circumstances to ignore a
particular item, but the full implications must be understood and
carefully weighed before choosing a different course.
- SHOULD NOT This phrase, or the phrase “NOT RECOMMENDED” mean that
there may exist valid reasons in particular circumstances when the
particular behavior is acceptable or even useful, but the full
implications should be understood and the case carefully weighed
before implementing any behavior described with this label.
- etc. see https://www.ietf.org/rfc/rfc2119.txt
A short note could be added to the documentation to explain this and link to the RFC.
Texts that adhere to these conventions often use these keywords in captital letters to make it clear the words are not used as normally, but they have a special meaning as specified in the RFC, e.g.
“The extension key MUST be unique worldwide if you publish your extension (on extensions.typo3.org).”
“The extension key MAY contain underscores.”
Language can be inherently vague and ambigous. Things like these make it much clearer. We do not need to do this excessively but I would like to suggest it in places that are currently vague and ambiguous. Especially where things will break if you do not follow the rules (which are sometimes specified as “conventions”, which does not really help to make it clear).
Examples, that might be improved by using these keywords: