Description
Your Godot version:
4.4
Issue description:
The documentation has two potential problems with admonitions (note/warning boxes):
Warning
is overused
Warning
is used for a wide range of severity levels, diluting it's meaning. The worst cases of this were fixed in #10252, and the docs now use Danger
for admonitions about potential data loss. But Warning
is still used for a wide range of severity, from side notes that should be read, potential misconceptions, conventions that are different than usual, or performance problems.
I think this can be improved by choosing either Attention
or Caution
and using it in place of 25-50% of current Warning
labels. Attention
and Caution
are both the same color as Warning
, but the words are less severe.
Stacked admonitions, potential general overuse of admonitions
In some places, multiple notes and warnings are stacked immediately one after another. Often this is fine, because each warning is semantically distinct. But in some cases it may be improved by combining some warnings.
@mhilbrunner in #10252 (comment):
[...M]ore long-term, I'd like to review every place where we use these notes and reconsider whether they are necessary, need to be in those boxes, or whether there are better alternatives. Whenever I stumble upon a section that has multiple of them plastered all over it, it looks... busy? Confusing? Dangerous, like there's thousands of little gotchas to keep in mind?
I'd like if we could avoid stacking these boxes. No easy task, however :)
Stats on current usages
Note
: 717 in 278 filesTip
: 102 in 62 filesSee also
: 153 results in 109 filesAttention
: 8 results in 6 files (!)Caution
: 2 results in 1 file (!)Warning
: 179 results in 114 filesDanger
: 6 results in 5 files