godotengine / godotengine/godot-docs
Improve usage of admonitions
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
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 https://github.com/godotengine/godot-docs/pull/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 https://github.com/godotengine/godot-docs/pull/10252#issuecomment-2479077509:
>[...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 files
- `Tip`: 102 in 62 files
- `See also`: 153 results in 109 files
- `Attention`: 8 results in 6 files (!)
- `Caution`: 2 results in 1 file (!)
- `Warning`: 179 results in 114 files
- `Danger`: 6 results in 5 files
### An example

Contributor guide
No contributing guide indexed for this repository
Research direction
Start by searching the documentation for Note, Warning, Attention, Caution, and other admonition labels, using the reported usage counts as a baseline. Review places with varied severity or stacked boxes, then update the selected admonitions and verify that the revised documentation uses clearer severity and avoids unnecessary stacking.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- godot
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100