Harmonize admontions in style guide #499
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This PR aims to harmonize our admonitions style guide to what is available on Docusaurus. The wording are adapted from [Grafana](https://grafana.com/docs/writers-toolkit/write/style-guide/style-conventions/) and [Codeberg](https://docs.codeberg.org/improving-documentation/style-guide/) style guides. Also with a little bit help of ChatGPT. The prompt is attached below : > Me : We want to harmonize our style guide on admonitions with whats available on docusaurus. What we have right now are adopted from Redhat. Redhat have four admonitions: Note, Important, Warning/Danger, and Tip. Docusaurus gives us five options : Note, Tip, Info, Important, Warning and Danger. Notice how docusaurus separate Warning and Danger, while Redhat don't. How would you describe those admonitions? > > ChatGPT : Sure, here's a breakdown of how you might describe each of these admonitions: >1. **Note**: Used to provide additional information or clarification that is not critical but can enhance understanding. >2. **Tip**: Offers a helpful suggestion or advice that can improve the user's experience or workflow. >3. **Info**: Provides general information that may be useful or relevant to the reader but isn't necessarily a warning or a tip. >4. **Important**: Highlights information that is crucial for the reader to understand or follow for successful completion of a task or to avoid issues. >5. **Warning**: Indicates a potential hazard, risk, or consequence that the reader should be aware of and take precautions against. >6. **Danger**: Indicates an imminent or severe risk that could lead to serious consequences if not addressed or avoided immediately. >While Redhat combines "Warning" and "Danger" into one category, Docusaurus separates them, perhaps to provide more granularity in communicating the severity of the cautionary message. Resolves getsolus#495
malfisya
force-pushed
the
admonitions
branch
from
0d63684
to
3e8abb7
Compare
davidjharder
requested changes
Feb 29, 2024
|
I disclose that information to be transparent. I understand that it can muddy the copyright. I just found it useful to brainstorm. I promise not not copy it verbatim out of ChatGPT or any other AI service. Cheers! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR aims to harmonize our admonitions style guide to what is available on Docusaurus. The wording are adapted from Grafana and Codeberg style guides. Also with a little bit help of ChatGPT. The prompt is attached below :
Resolves #495