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

Change warning boxes to danger boxes if data loss can occur #10252

Merged
merged 1 commit into from
Nov 15, 2024

Conversation

tetrapod00
Copy link
Contributor

Promotes warning blocks to danger blocks if any loss of data can occur.

Prior to this PR, the documentation seems to use:

  • "Note" for optional information, used often,
  • "Caution" only twice,
  • "Attention" only 8 times,
  • "Danger" once, in the tool script page,
  • and "Warning" for the vast majority of everything else. "Warning" covers a very wide range of severity, from side notes that should be read, potential misconceptions, conventions that are different than usual, or performance problems. It's used often enough that you might start ignoring the warning boxes.

There are a few instances where data loss or actual harm can occur, and these instances should use "Danger" instead of "Warning" to stand out. I checked all the existing "Warning" boxes, and also checked for "backup" and "version control" mentions to find anything else.

Later, I'd like to investigate maybe using the lesser-used Attention and Caution notes more often, for notes that are less severe. Both of these are still the same color as Warning, but the words have different severity. I think Attention could be used in many cases where Warning currently is.

@@ -169,7 +169,7 @@ you have two options:
Distributing a custom platform port
-----------------------------------

.. warning::
.. danger::
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on the same standard of potential legal harm used to change this warning, the warning in Complying with licenses could also be a danger:

.. warning::
The recommendations in this page **are not legal advice.** They are provided
in good faith to help users navigate license attribution requirements.

However, that one occurs early in the docs in the About section, so a danger might scare people off. And I think the potential harm of getting the MIT license a little wrong is less than the potential harm of distributing an NDA console port 🤷

@tetrapod00 tetrapod00 added enhancement 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 14, 2024
@mhilbrunner
Copy link
Member

mhilbrunner commented Nov 15, 2024

Later, I'd like to investigate maybe using the lesser-used Attention and Caution notes more often, for notes that are less severe. Both of these are still the same color as Warning, but the words have different severity. I think Attention could be used in many cases where Warning currently is.

I agree. Also, and more 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 :)

@mhilbrunner mhilbrunner merged commit 316f05f into godotengine:master Nov 15, 2024
1 check passed
@mhilbrunner
Copy link
Member

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:contributing Issues and PRs related to the Contributing/Development section of the documentation area:manual Issues and PRs related to the Manual/Tutorials section of the documentation enhancement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants