diff --git a/detector/detector.go b/detector/detector.go
index 5c85bd7e..e3a56c0c 100644
--- a/detector/detector.go
+++ b/detector/detector.go
@@ -59,11 +59,17 @@ type Finding struct {
 // information specific to the target (e.g. which files were found vulnerable).
 type Advisory struct {
 	// A unique ID for the finding.
-	ID          *AdvisoryID
-	Type        TypeEnum
-	Title       string
+	ID   *AdvisoryID
+	Type TypeEnum
+	// Title, short description and recommendation steps for the finding. Users should be able to rely
+	// on these fields to understand the vulnerability and remediate it.
+	// Title of the finding, e.g. "CVE-2024-1234 - RCE Vulnerability on Foo".
+	Title string
+	// Description of the finding, e.g. "Foo prior to version 1.2.3 is affected by a Remote Code
+	// Execution vulnerability.".
 	Description string
-	// Remediation instructions, e.g. "update to latest version".
+	// Recommendation for how to remediate the finding, e.g. "Upgrade Foo to version 1.2.4 or
+	// higher.".
 	Recommendation string
 	Sev            *Severity
 }
diff --git a/docs/new_detector.md b/docs/new_detector.md
index 2b829bfc..a9552ba5 100644
--- a/docs/new_detector.md
+++ b/docs/new_detector.md
@@ -16,11 +16,12 @@ as an example.
 1.  Set up your detector package in an [appropriate location](#code-location).
 1.  Create a struct that implements
     [`Detector`](/detector/detector.go):
-    *   Implement `Name()` to return a unique name, e.g. `cve/nginxldapauth`.
+    *  Implement `Name()` to return a unique name, e.g. `cve/nginxldapauth`.
     *   Implement `Version()` to return 0. Increase it in the future whenever
         larger changes are made to the detector.
     *   Implement `Scan()` (see [param list](#scan-parameters)) to run your
         detection logic and [return](#output-format) the security findings.
+1.  Appropriately fill the "Description" and "Recommendation" advisory fields
 1.  Write tests.
 1.  Register your detector in
     [list.go](/detector/list/list.go)