Skip to content

Commit

Permalink
Harmonize admontions in style guide
Browse files Browse the repository at this point in the history
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
  • Loading branch information
malfisya committed Feb 29, 2024
1 parent 87e90fc commit 3e8abb7
Showing 1 changed file with 6 additions and 3 deletions.
9 changes: 6 additions & 3 deletions docs/user/contributing/style.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,16 +34,19 @@ _In alphabetical order, not order of importance._

### Admonitions

This section is based on the [Red Hat supplementary style guide.](https://redhat-documentation.github.io/supplementary-style-guide/#admonitions).
This section is based on the [Red Hat supplementary style guide](https://redhat-documentation.github.io/supplementary-style-guide/#admonitions).

Admonitions should draw the reader’s attention to certain information. Keep admonitions to a minimum, and avoid placing multiple admonitions close to one another. If multiple admonitions are necessary, restructure the information by moving the less-important statements into the flow of the main content. See the [Docusaurus documentation](https://docusaurus.io/docs/markdown-features/admonitions) to learn the correct syntax.

| Type | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Note | Additional guidance or advice that improves product configuration, performance, or supportability |
| Important | Advisory information essential to the completion of a task or default configuration settings. Users must not disregard this information. |
| Warning/Danger | Information about potential system damage, data loss, or a support-related issue if the user disregards this admonition. If available, offer information to avoid the problem in the future or state where to find more information. |
| Tip | Recommendations, suggestions, and alternative methods that might not be obvious. Tips are not essential to using the product. |
| Info | General information about product that may be useful or relevant to user. |
| Important | Advisory information essential to the completion of a task or default configuration settings. Users must not disregard this information. |
| Warning | Information that warns the user to proceed with caution. Warning emphasizes a course of action’s potential downsides. |
| Danger | Information about imminent system damage, data loss, or a support-related issue if the user disregards this admonition. If available, offer information to avoid the problem in the future or state where to find more information. |


## Code blocks

Expand Down

0 comments on commit 3e8abb7

Please sign in to comment.