SONAR-12027 update docs for Hotspot Actions

1 files changed, 27 insertions, 22 deletions

diff --git a/server/sonar-docs/src/pages/user-guide/security-hotspots.md b/server/sonar-docs/src/pages/user-guide/security-hotspots.md
index 859a44a2015..018819cb2cc 100644
--- a/server/sonar-docs/src/pages/user-guide/security-hotspots.md
+++ b/server/sonar-docs/src/pages/user-guide/security-hotspots.md
@@ -5,49 +5,54 @@ url: /user-guide/security-hotspots/
 
 ## What is a Security Hotspot?
 
-Unlike Vulnerabilities, Security Hotspots aren't necessarily issues that are open to attack. However, Security Hotspots highlight security-sensitive pieces of code that someone focused on security needs to review. Upon review, that security-focused developer or reviewer might find that a Security Hotspot is in fact a Vulnerability that needs to be fixed. 
+Unlike Vulnerabilities, Security Hotspots aren't necessarily issues that are open to attack. Instead, Security Hotspots highlight security-sensitive pieces of code that need to be manually reviewed. Upon review, you might be find a Vulnerability at a Security Hotspot location that needs to be fixed or that there is no threat. 
 
 ## Why are Security Hotspots Important?
 
-Security Hotspots help focus the efforts of developers or reviewers who are manually checking security-sensitive code. Reviewing Security Hotspots allows you to:
+Security Hotspots help focus the efforts of developers who are manually checking security-sensitive code. Reviewing Security Hotspots allows you to:
 
-* **Fix security issues** – Reviewing Security Hotspots gives you the opportunity to detect true vulnerabilities and ensure issues are fixed before merging pull requests or releasing your branch.
-* **Learn about security** – {instance} explains why your code was identified as a Security Hotspot and the link between your Hotspots and well-known attacks or weaknesses such as SQL Injection, Weak Cryptography, or Authentication. Knowing this makes developers aware of when they're working on security-sensitive code and helps them avoid creating Vulnerabilities.
+* **Fix security issues** – Reviewing Security Hotspots gives you the opportunity to detect vulnerabilities and ensure issues are fixed before merging pull requests or releasing your branch.
+* **Learn about security** – {instance} explains why your code was identified as a Security Hotspot and the link between your Security Hotspots and well-known attacks or weaknesses such as SQL Injection, Weak Cryptography, or Authentication. Knowing this makes you aware of when you're working on security-sensitive code and helps you avoid creating Vulnerabilities.
 
 ## Security Hotspot Lifecycle
-Security Hotspots have a dedicated lifecycle and must be reviewed by a user with the "Administer Security Hotspots" permission. 
+Security Hotspots have a dedicated lifecycle and must be reviewed by someone with the "Administer Security Hotspots" permission. 
 
 ### Status
 
 Through the lifecycle, a Security Hotspot takes one of the following statuses:
 
-* **Open** - set by {instance} on new Security Hotspots
-* **Resolved** (Won't Fix) - set automatically by {instance} when a reviewer accepts the fix done by a developer on a Manual Vulnerability or when a reviewer clears an open Hotspot or manual Vulnerability.
-* **To Review** - set automatically when a developer requests a review on a manual Vulnerability.
-* **Reopened** - set when a developer dismisses an open manual Vulnerability or when a reviewer manually reopens a resolved Security Hotspot in order to run a new audit on it.
+* **To Review** – the default status of new Security Hotspots set by {instance}. A Security Hotspot has been reported and needs to be checked.
+* **In Review** – the Security Hotspot is being checked to make sure there isn't a vulnerability in the code.
+* **Reviewed** – the Security Hotspot has been checked and no security issue was found.
 
 A Security Hotspot is only closed if the code containing it is deleted. A Security Hotspot's status will be "Removed" if the rule in the project's Quality Profile identifying it is removed.
 
 ### Actions
 
-Security Hotspots allow the following actions:
+You can perform the following actions on Security Hotspots:
 
-* **Detect** - Confirms a Security Hotspot as a true issue and manually opens a Vulnerability. Requires "Administer Security Hotspots" permission on the project.
-* **Clear** - Marks a Security Hotspot or manually opened Vulnerability as being without issue and shouldn't be fixed. Requires "Administer Security Hotspots" permission on the project.
-* **Request Review** - Request that a reviewer analyzes changes made to fix a manually opened Vulnerability.
-* **Reject** - After review, reject the fix for a manually opened Vulnerability and return it to an open issue. Requires "Administer Security Hotspots" permission on the project.
+* **Resolve as Reviewed** - There is no vulnerability in the code.
+* **Set as In Review** - A review is in progress to check for a vulnerability
+* **Reset as To Review** - The Security Hotspot needs to be analyzed again.
+* **Open as Vulnerability** - There's a Vulnerability in the code that must be fixed.
 
 ### Workflow
 
-If a reviewer with "Administer Security Hotspots" permission determines a Hotspot is actually a Vulnerability, the reviewer changes the status from its current state (probably **Open**) to **Detect**. This converts the Security Hotspot to a Vulnerability, and the developer who last touched the line will receive "new issue" notifications (if she's signed up to get them).
+When {instance} detects a Security Hotspot, it is set as **To Review**. From here, you can perform the following actions on the Security Hotspot:
+* **Open as a Vulnerablility** if you find a Vulnerability in the code at the Security Hotspot location that must be fixed.
+* **Resolve as Reviewed** if you don't find a Vulnerability in the code at the Security Hotspot location.
+* **Set as In Review** if you want to flag the Security Hotspot to show that you are checking it or about to check it for Vulnerabilities. This is an optional step in the workflow. 
 
-Once a Vulnerability is *Detect*ed at a Security Hotspot location, the following occurs:
+If you set a Security Hotspot to **In Review**, it can either be marked:
+* **Open as Vulnerability** if you find a Vulnerability in the code that must be fixed.
+* **Resolve as Reviewed** if you don't find a Vulnerability in the code.
+
+When you determine there is a Vulnerability at a Security Hotspot location and select **Open as a Vulnerability**, its status changes from **To Review** or **In Review** to **Open**. This converts the Security Hotspot to a Vulnerability, and the developer who last touched the line of code will receive "new issue" notifications (if she's signed up to get them).
+
+Once a Vulnerability is **Open**ed at a Security Hotspot location, the following occurs:
 
 1. The Security Hotspot is assigned to the appropriate developer, and the developer makes a fix.
-2. The developer must then **Request Review** *via the UI*. The request moves the Vulnerability back to Security Hotspot. 
-3. The reviewer either **Accepts** or **Rejects** the fix. 
-	* Accepting the fix marks the Security Hotspot "Won't Fix." 
-	* Rejecting the fix turns the Security Hotspot back into a Vulnerability and puts it back in the developer's queue.
+2. The developer then marks the Vulnerability **Resolve as Reviewed** *via the UI* which moves the Vulnerability back to being a Security Hotspot. 
+3. The Security Hotspot is then marked as **Reviewed** and it's status is **Fixed**. 
 
-### Marking a Hotspot "Won't Fix"
-The `Won't Fix` designation indicates that a Hotspot has been reviewed and there is no way, as of now, to exploit this piece of code to create an attack.
+A reviewed Security Hotspot can be reopened as a Vulnerability at any point if it's determined to be a true issue.