Improve usage of admonitions #10268
Labels
area:about
Issues and PRs related to the About section of the documentation and other general articles
area:contributing
Issues and PRs related to the Contributing/Development section of the documentation
area:getting started
Issues and PRs related to the Getting Started section of the documentation
area:manual
Issues and PRs related to the Manual/Tutorials section of the documentation
enhancement
Your Godot version:
4.4
Issue description:
The documentation has two potential problems with admonitions (note/warning boxes):
Warning
is overusedWarning
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 useDanger
for admonitions about potential data loss. ButWarning
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
orCaution
and using it in place of 25-50% of currentWarning
labels.Attention
andCaution
are both the same color asWarning
, 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):
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 filesURL to the documentation page (if already existing):
The text was updated successfully, but these errors were encountered: