docs: maintainer annotations (#4235)

Signed-off-by: Raghav Kaul <[email protected]>

Author: raghavkaul

README.md

@@ -419,12 +419,11 @@ RESULTS
 |---------|------------------------|--------------------------------|--------------------------------|---------------------------------------------------------------------------|
 ```
 
-##### Showing Maintainers Annotations (Experimental)
+##### Showing Maintainers Annotations
 
-To see the maintainers annotations for each check, use the `--show-annotations` option.
-
-For more information on how to configure annotations or what are the available annotations, see [the configuration doc](config/README.md).
+**Maintainer Annotations** let maintainers add context to display alongside Scorecard check results. Annotations can provide users additional information when Scorecard has an incomplete assessment of a project's security practices. To see the maintainers annotations for each check, use the `--show-annotations` option.
 
+For more information on available annotations or how to make annotations, see [the configuration doc](config/README.md).
 
 ##### Using a GitLab Repository
 

config/README.md

@@ -1,6 +1,6 @@
 # Maintainer Annotations
 
-**Maintainer Annotations** are an experimental feature that let maintainers add context to Scorecard check results. Annotations can inform users when Scorecard is incorrectly assessing a project's security practices.
+**Maintainer Annotations** let maintainers add context to display alongside Scorecard check results. Annotations can provide users additional information when Scorecard has an incomplete assessment of a project's security practices.
 
 ## Annotating Your Project