Add additional LayC guidance in docs (#3193)

Adding in additional material and a bit of refactoring for clarity.

## Review

A dedicated reviewer checked the rule description successfully for:

- [ ] logical errors and incorrect information
- [ ] information gaps and missing content
- [ ] text style and tone
- [ ] PR summary and labels follow [the
guidelines](https://github.com/SonarSource/rspec/#to-modify-an-existing-rule)

---------

Co-authored-by: Loris S. <91723853+loris-s-sonarsource@users.noreply.github.com>

docs/description.adoc

@@ -31,7 +31,7 @@ The possible sections for this format are the following:
 
 Third-level and fourth-level titles (`+=== Title t3+` and `+==== Title t4+`) are not checked for this type of rule.
 
-=== 2. Education Format
+=== 2. Learn as You Code Rule Format
 
 This format is defined as follows:
 
@@ -79,14 +79,17 @@ Goal: The title (or message) of a rule might not always be clear due to its shor
 Start at the basics and go into more depth to explain the concepts behind this type of issue. This is most likely the place where a lot of the content will be. +
 This is the place to tell the “story” of the rule, including the impact of leaving it unfixed. We should include code samples wherever needed to make it easier to understand
 what is going on. This can be in the form of noncompliant and compliant code in a single code box (noncompliant lines should always be highlighted with the corresponding comment
-“// Noncompliant” optionally followed by some explanation) if that is clearer. This first tab will be like a blog post style with a free format explaining what the rule is
+“// Noncompliant” optionally followed by some explanation) if that is clearer. This first tab could use a blog post style with a free format explaining what the rule is
 detecting and why. Feel free to use “What is the potential impact?” title if it makes sense, or any other titles you find useful. +
-Goal: Understand the concepts behind an issue.
+Goal: Understand the concepts behind an issue and why it matters.
 +
 ** *What is the potential impact?* (level 3 title) [Optional]
 +
-What is the risk for me? What can go wrong?
-This section can include multiple concrete threats as well.
+This subsection aims to address questions such as the following: +
+What is the risk for me?  What is the risk for my organization? What is the risk for the users? What can go wrong? +
+This section aims to talk about the impacts on the software, depending on the code qualities this issue is linked to: security, reliability, or maintainability. **(see <<metadata.adoc#code-field,Impacts>>.)**
++
+Consequently, this section can also talk about the impacts on the ecosystem of this software. For example, impacts on the organization, on the users, and impact in terms of regulations.
 https://github.com/SonarSource/rspec/blob/a51217c6d91abfa5e1d77d0ae0843e3903adf2d0/rules/S3649/impact.adoc[_Example._] +
 Goal: Our users should understand the impact of this issue on their project.
 +
@@ -130,9 +133,6 @@ This section lists Sonar rules related to the current one. The rule ID(s) should
 +
 xref:link_formatting.adoc[Standard for links is defined in this document.]
 
-
-Note that most sections and subsections are optional, only the `Why is this an issue?` main section is mandatory.
-
 Content of the section "_How to fix it_ / _How to fix it in {Framework Display Name}_" can either be generic or framework specific.
 
 When the content is generic, the "_How to fix it_" title must be used, and the section should only appear once. Example:
@@ -217,6 +217,27 @@ This is important, as this format will be expected by the analyzers when loading
 Furthermore, the display name of the framework has to match an allowed framework
 display name, as defined in <<header_names/allowed_framework_names.adoc#,this allowed framework names file>>.
 
+==== General guidance
+
+Most sections and subsections of the Learn as You Code rule format are optional, only the `Why is this an issue?` main section is mandatory. 
+The goal is to provide the right level of guidance so that users get the right information from the rules at the right time.
+Do not feel obliged to use every section or sub-section if omitting them would lead to a better user experience.
+
+==== Guidelines if you aren’t sure where something belongs in a rule
+* If you need the information to fix the issue, but only the first time, it probably belongs in ‘Why is this an issue?’
+* If you need the information to fix the issue every time, it probably belongs in ‘How to fix it?’
+* If you don’t need the information to fix the issue, but it will help users grow their knowledge, it probably belongs in ‘Resources’ (this maps to the 'More Info' tab in the products)
+
+By being careful about what goes where, we help to ensure that users get exactly what they need, when they need it.
+
+==== Guidelines on content focus
+
+We want to help users to create Clean Code. Rule content should focus on the manner in which the code is not clean, why this is an issue, and how to remedy this. 
+Rules should talk about the potential impact on software quality in the 'What is the potential impact?' sub-section.
+
+For example, if you are talking about a locking issue, it makes sense to focus on the logical issues that could lead to a deadlock and how to fix that in the main rule content. 
+The implications of a deadlock on the application reliability would then go into the 'What is the potential impact?' sub-section.
+
 == Code Examples
 
 Whenever possible, prefix your code blocks with `[source,language]`, in order to get syntax coloring.
@@ -328,4 +349,4 @@ This way, your comment will only be visible in GitHub preview and on the Search
 
 You can share content between rules by using the `shared_content` folder at the root of the repository.
 
-Any included content for a rule can only come from the folder of the rule being described, `shared_content`, or any of their subfolders.
+Any included content for a rule can only come from the folder of the rule being described, `shared_content`, or any of their subfolders.