docs: add new paragraph in CODING_STANDARDS.md

CODING_STANDARDS.md

@@ -45,6 +45,21 @@ In SCSS code, always use `//` style comments.
 
 In HTML code, use `<!-- ... -->` comments, which will be stripped when packaging a build.
 
+#### Write clear and exhaustive documentation
+
+Every time a component is created, a `readme.md` file is generated;
+don't underestimate its value, as it will be the documentation entry point for consumers.
+
+The `generate` script will create a base structure for the component description; try to stick at it if you can.
+
+Start with a brief sentence which describes the main purpose of the component and why it should be used;
+if it is related to other components, mention them and add a link to their documentation.
+
+Then describe how the component should be used, adding code examples:
+if it's a presentational one explain its graphic variants using the `### Style` paragraph,
+while if it's a complex one you could use the `### Interaction` paragraph.
+Almost all the components has `### Slots` and can have different `### States`; describe how they can be used.
+
 #### Prefer small, focused modules
 
 Keeping modules to a single responsibility makes the code easier to test, consume, and maintain.

convenience/generate-component/boilerplate/readme.md

@@ -1,30 +1,29 @@
-> Explain the use and the purpose of the component, add minor details if needed, and provide a basic example.<br>
-> If you reference other components, link at least once their documentation page (the path must start from "/docs/...").<br>
-> Use triple backticks for the examples code block.
+> Explain the use and the purpose of the component; add minor details if needed and provide a basic example.<br>
+> If you reference other components, link their documentation at least once (the path must start from _/docs/..._ ).<br>
+> For the examples, use triple backticks with file extension (```` ```html <code here>``` ````).<br>
+> The following list of paragraphs is only suggested; remove, create and adapt as needed.
 
-The `__name__` is a component...
+The `__name__` is a component . . .
 
 ```html
 <__name__></__name__>
 ```
 
-> The following list of "## Paragraph" is only suggested; remove, create and adapt based on needs.
-
 ## Slots
 
 > Describe slot naming and usage and provide an example of slotted content.
 
 ## States
 
-> Describe the component states (`disabled`, `readonly`, etc.) and provide an example.
+> Describe the component states (`disabled`, `readonly`, etc.) and provide examples.
 
 ## Style
 
-> Describe the properties which change the component visualization (`size`, `negative`, etc.) and provide an example.
+> Describe the properties which change the component visualization (`size`, `negative`, etc.) and provide examples.
 
 ## Interactions
 
-> Describe how it's possible to interact with the component (open and close a `sbb-dialog`, dismiss a `sbb-alert`, etc.) and provide an example.
+> Describe how it's possible to interact with the component (open and close a `sbb-dialog`, dismiss a `sbb-alert`, etc.) and provide examples.
 
 ## Events