Skip to content

Improve usage of admonitions #10268

Open
Open
@tetrapod00

Description

@tetrapod00

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 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:aboutIssues and PRs related to the About section of the documentation and other general articlesarea:contributingIssues and PRs related to the Contributing/Development section of the documentationarea:getting startedIssues and PRs related to the Getting Started section of the documentationarea:manualIssues and PRs related to the Manual/Tutorials section of the documentationenhancement

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions