From 6562a7bea453081b1b41f309ae18d578c1133879 Mon Sep 17 00:00:00 2001 From: Muhammad Alfi Syahrin <101771435+malfisya@users.noreply.github.com> Date: Thu, 29 Feb 2024 22:51:09 +0700 Subject: [PATCH] Harmonize admontions in style guide (#499) * 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 getsolus/help-center-docs#495 --------- Co-authored-by: David Harder --- docs/user/contributing/style.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/user/contributing/style.md b/docs/user/contributing/style.md index f7f9db658..8c4417002 100644 --- a/docs/user/contributing/style.md +++ b/docs/user/contributing/style.md @@ -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 the topic at hand 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