Update description.adoc to allow for freeform text in 'how' tab

We allow for freeform text in the 'why' tab. We want to allow for this in the 'how' tab.

I have updated the language a bit to talk about 'story-telling' rather than 'blog style' because I think that better reflects how we expect this approach to be used. 

I have also removed the (optional) markers and just added in the one (mandatory) marker needed since the optional markers weren't correct anymore.

docs/description.adoc

@@ -43,25 +43,27 @@ This format is defined as follows:
 * Short description (no title)
 
 // This needs to be kept in sync with the [maps in the validation script](https://github.com/SonarSource/rspec/blob/master/rspec-tools/rspec_tools/validation/description.py#L32-L39).
-* Why is this an issue?
-** What is the potential impact? (optional)
-** Exceptions (optional)
-** (any other titles) (optional)
-* How to fix it (optional)
+* Why is this an issue? (mandatory)
+** What is the potential impact?
+** Exceptions
+** (any other titles)
+* How to fix it
 ** Code examples
 *** Noncompliant code example
 *** Compliant solution
 ** How does this work?
 ** Pitfalls
 ** Going the extra mile
-* How to fix it in {Framework Display Name} (optional)
+** (any other titles)
+* How to fix it in {Framework Display Name}
 ** Code examples
 *** Noncompliant code example
 *** Compliant solution
 ** How does this work?
 ** Pitfalls
 ** Going the extra mile
-* Resources (optional)
+** (any other titles)
+* Resources
 ** Documentation
 ** Articles & blog posts
 ** Conference presentations
@@ -84,8 +86,8 @@ 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 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. +
+“// Noncompliant” optionally followed by some explanation) if that is clearer. This first tab could use a freeform 'story-telling' style explaining what the rule is
+detecting and why. Feel free to use the “What is the potential impact?” title if it makes sense, or any other titles you find useful. +
 Goal: Understand the concepts behind an issue and why it matters.
 +
 ** *What is the potential impact?* (level 3 title) [Optional]
@@ -101,7 +103,8 @@ Goal: Our users should understand the impact of this issue on their project.
 * *How to fix it* or *How to fix it in `{Framework Display Name}`* (level 2 title) [Optional; the title depends on whether the description is generic or framework-specifc. See examples below.]
 +
 This section consists of one or multiple fixes for this type of issue (`Noncompliant code example` vs. `Compliant solution`). There can be multiple fixes for different libraries and/or frameworks.
-If the fix for the rule is trivial (quickfix is available, it is easily inferred from the title and/or message), this section should be omitted and the fix could be mentioned in the previous section. +
+If the fix for the rule is trivial (quickfix is available, it is easily inferred from the title and/or message), this section should be omitted and the fix could be mentioned in the previous section. 
+This tab could also use a freeform 'story-telling' style if that makes it clearer for the user. Feel free to use any of the titles below, or any other titles you find useful. +
 Goal: Get an idea of how this issue can be fixed for my project/framework, why this works, what to look out for, and also how to continue improving on this topic.
 +
 ** *How does this work?* (level 3 title) [Optional]