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.

Sign up for GitHub

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

Jump to bottom

Harmonize admontions in style guide #495

Closed
davidjharder opened this issue Feb 27, 2024 · 1 comment · Fixed by #499
Closed

Harmonize admontions in style guide #495

davidjharder opened this issue Feb 27, 2024 · 1 comment · Fixed by #499
Labels
Good First Issue

Comments

@davidjharder
Copy link
Member

The admonitions section of the style guide: https://help.getsol.us/docs/user/contributing/style/#admonitions does not match the admonitions that are actually available to be used from docusaurus: https://docusaurus.io/docs/markdown-features/admonitions

This happened when we moved from docusaurus 2.x to 3.x
@malfisya
Copy link
Member

I think I can help with this. Will look at it more tomorrow. Cheers!

malfisya added a commit to malfisya/help-center-docs that referenced this issue Feb 29, 2024
@malfisya
Harmonize admontions in style guide
0d63684 
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 malfisya mentioned this issue Feb 29, 2024
Merged
malfisya added a commit to malfisya/help-center-docs that referenced this issue Feb 29, 2024
@malfisya
Harmonize admontions in style guide
3e8abb7 
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
davidjharder added a commit that referenced this issue Feb 29, 2024
@malfisya @davidjharder
Harmonize admontions in style guide (#499)
6562a7b 
* Harmonize admontions in style guide

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

---------

Co-authored-by: David Harder <david@davidjharder.ca>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Good First Issue
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Harmonize admontions in style guide malfisya/help-center-docs
2 participants
@davidjharder @malfisya