godotengine / godotengine/godot-docs

Improve usage of admonitions

Open
#10,268 0 comments 1 reaction 0 assignees View on GitHub
area:about area:engine details area:getting started area:manual enhancement
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

![Image](https://github.com/user-attachments/assets/362c74fd-3871-414c-abae-96894f4bdfbf)

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.