Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve usage of admonitions #10268

Open
tetrapod00 opened this issue Nov 15, 2024 · 0 comments
Open

Improve usage of admonitions #10268

tetrapod00 opened this issue Nov 15, 2024 · 0 comments
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

Comments

@tetrapod00
Copy link
Contributor

tetrapod00 commented Nov 15, 2024

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

URL to the documentation page (if already existing):

@tetrapod00 tetrapod00 added enhancement area:about Issues and PRs related to the About section of the documentation and other general articles 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 area:contributing Issues and PRs related to the Contributing/Development section of the documentation labels Nov 15, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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
Projects
None yet
Development

No branches or pull requests

1 participant