changes as per new approach and vitpress standards

resources/guidelines/documentation-guidelines/01-general.md

@@ -27,12 +27,15 @@ It is important to consider the background of the potential audience reading you
 | Product owner/ Manager | <ul><li>Responsibilities pertaining to the product life cycle</li></ul> |
 | Tech writers | <ul><li>Document all product details</li></ul> |
 
-## List of docs maintained by us
+## Applicable documents: style guide coverage
 
-* [Developer Guide](/docs/)
+* [Developer docs](https://developer.shopware.com/docs/)
 * [API Reference Guide](https://shopware.stoplight.io/)
 * [PWA](https://shopware-pwa-docs.vuestorefront.io/)
 * [Admin Extension SDK](https://shopware.github.io/admin-extension-sdk/)
+* [Meteor icon kit](https://shopware.github.io/meteor-icon-kit/)
+* [Frontend docs](https://frontends.shopware.com/)
+* [Component library](https://component-library.shopware.com/)
 
 ## Word list
 

resources/guidelines/documentation-guidelines/02-conceptual-structure.md

@@ -13,23 +13,7 @@ To give our readers a good experience, we have established writing guidelines fo
 
 ## Concepts
 
-This section articulates the core concepts of Shopware. It is an entry point to learn about how the platform is organized. This section rather **explains** than **shows** how things work; therefore, please follow the guidelines below when writing *Concepts*.
-
-* **Introduction** - Introduce the concept by its purpose — for example, *This article discusses the Shopware cart. Along the way, you will find answers to the following questions:*
-  * *What is the cart?*
-  * *What can it contain?*
-  * *How does it relate to users and orders?*
-
-* **Description** - Give a short description of the concept within 2-3 sentences — for example,  *"The cart is a collection of items a user wants to buy within the shop. It might contain products, discounts, or virtual products like bundles or configurable products. Eventually, a cart gets converted into an order. This process is called checkout."*
-
-Use cross-references to help users fully understand the text — for example, provide a link to *configurable products* or *checkout* articles. Don't use terms like *"custom products"* as these are Shopware-specific, and newcomers may find it difficult to understand.
-
-* **Comprehensive explanation** - Explain the concept in detail with examples, illustrations, tables, graphs, or pseudo-code.
-
-  Don't use any Shopware-specific source code. Using source code within a conceptual article has the following drawbacks:
-  * It introduces another dependency that has to be maintained.
-  * It builds on the presumption that readers know the given language and context.
-  * People tend to copy & paste without context.
+This section articulates the core concepts of Shopware. It is an entry point to learn about how the platform is organized. This section rather **explains** than **shows** how things work
 
 ## Products
 

resources/guidelines/documentation-guidelines/03-language-and-grammar.md

@@ -47,7 +47,7 @@ It is okay to use passive voice in the following cases:
 
 * In general, use the second-person instead of the first-person, such as *you* instead of *we* or *I*. However, first-person usage is an exception for FAQs.
 
-* If you are guiding the reader to perform something, use an imperative form with an implicit you. For example:
+* If you are guiding the reader to perform something, use an imperative form with an implicit *you*. For example:
 
 ::: tip
   **Recommended** - Create a PDF file.

resources/guidelines/documentation-guidelines/04-fonts-and-formats/01-text.md

@@ -41,13 +41,13 @@ Follow the below steps to start your project:
 1. Create a docker-compose.yml file
 2. Start the Docker
 3. Prepare Development
-...
+4. ...
 ```
 
 * **Regular bulleted list** - Use this for general enlisting with an asterisk `*` in Markdown to signify bulleted lists.
 
 ```text
-You can install Shopware on Mac with the help of other tools:
+You can install Shopware on Mac with the help of tools like:
 
 * Docker
 ```

resources/guidelines/documentation-guidelines/04-fonts-and-formats/02-code.md

@@ -123,7 +123,17 @@ const pay_type = <Payment type=COD />;
 
 * Use three dots (...) on a separate line to indicate that more lines of output are omitted from the sample output.
 
-* Refer to [Syntax & Guidelines](https://handbook.shopware.com/Product/Guides/Development/DeveloperDocumentation#syntax--guidelines) for more examples.
+## Blockquote
+
+* Blockquotes are represented by `>`
+
+    ```text
+    
+    > Added A Name preset according to new naming scheme.
+    
+    ``````
+
+* To add blockquotes within a blockquote, use `>>`
 
 ## Items to put in ordinary (non-code) font
 

resources/guidelines/documentation-guidelines/05-methodize-assets.md

@@ -45,6 +45,8 @@ To create a pictorial illustration, reach out to the Shopware design team.
 
 * An introductory sentence should precede most images.
 
+* For UML diagrams use [Mermaid](https://mermaid.live/) to create one and add the diagram code in code block.
+
 ## File
 
 Every file added to a folder can have a naming convention as:

resources/guidelines/documentation-guidelines/06-doc-process.md

@@ -45,6 +45,25 @@ In your first draft:
 * Work with cross-references \(knowledge is a network, not a one-way street \).
 * Try to use non-Shopware-specific language when possible or provide a link to its description (e.g., "DAL").
 
+### Guidelines to writing concepts
+
+* **Introduction** - Introduce the concept (for example, cart) by its purpose in such a way that it answers folowing general questions:
+  * *What is a cart?*
+  * *What can it contain?*
+  * *How does it relate to users and orders?*
+  * *What can the readers expect in the further connected articles?*
+
+Use cross-references to help users fully understand the text — for example, provide a link to *configurable products* or *checkout* articles. Don't use terms like *"custom products"* as these are Shopware-specific, and newcomers may find it difficult to understand.
+
+* **Comprehensive explanation** - Explain the concept in detail with examples, illustrations, tables, graphs, or pseudo-code.
+
+  Don't use any Shopware-specific source code. Using source code within a conceptual article has the following drawbacks:
+  * It introduces another dependency that has to be maintained.
+  * It builds on the presumption that readers know the given language and context.
+  * People tend to copy & paste without context.
+
+* **Conclusions** - If possible add a connective statement to the next article that follows.
+
 ## Review
 
 After writing the first 30%, consult a reviewer to give some initial feedback. Discuss the current progress and re-arrange some parts if needed.
@@ -69,4 +88,6 @@ If a documented feature or functionality is introduced within major versions (an
 This functionality is available starting with Shopware 6.4.3.0.
 :::
 
+
+
 **Your contribution is our pride!**