search

getsolus / help-center-docs

Solus's Help Center documentation as well as previous User Guide.
https://help.getsol.us
GNU General Public License v2.0
57 stars 83 forks source link

Harmonize admontions in style guide #499

Closed malfisya closed 9 months ago

malfisya commented 9 months ago

Description

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/help-center-docs#495
malfisya commented 9 months ago

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!