From 87aa64f08693a671447541d616f3cf438e6bb03f Mon Sep 17 00:00:00 2001
From: Lukasz Mierzwa <lukasz@cloudflare.com>
Date: Fri, 28 Jan 2022 15:17:43 +0000
Subject: [PATCH] Refactor docs

---
 README.md             | 10 ++++++++--
 docs/CONFIGURATION.md | 34 ++++++++++++++++++++++------------
 2 files changed, 30 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 70749672..632ea4de 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ pint is a Prometheus rule linter.
 
 ## Usage
 
-There are two modes it works in:
+There are three modes it works in:
 
 - CI PR linting
 - Ad-hoc linting of a selected files or directories
@@ -13,6 +13,8 @@ There are two modes it works in:
 
 ### Pull Requests
 
+Run it with `pint ci`.
+
 It currently supports git for which it will find all commits on the current branch that are not
 present in parent branch and scan all modified files included in those changes.
 
@@ -74,12 +76,16 @@ scrape_configs:
       - targets: ['localhost:8080']
 ```
 
+## Release Notes
+
+See [CHANGELOG.md](/CHANGELOG.md) for history of changes.
+
 ## Quick start
 
 Requirements:
 
 - [Git](https://git-scm.com/)
-- [Go](https://golang.org/) >=1.17
+- [Go](https://golang.org/) - current stable release
 
 1. Build the binary:
 
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index c1cee8f5..3c4855f5 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -189,7 +189,12 @@ rule {
 
 # Check definitions
 
-## Aggregation
+## promql/syntax
+
+This check will report any syntax errors in a PromQL query on any rule.
+It's enabled by default.
+
+## promql/aggregate
 
 This check is used to inspect promql expressions and ensure that specific labels
 are kept or stripped away when aggregating results. It's mostly useful in recording
@@ -249,7 +254,7 @@ aggregate ".+" {
 }
 ```
 
-## Annotations
+## alerts/annotation
 
 This check is used to ensure that all required annotations are set on alerts and that
 they have correct values.
@@ -293,7 +298,12 @@ rule {
 }
 ```
 
-## Labels
+## alerts/for
+
+This check will warn if an alert rule uses invalid `for` value
+or if it passes default value that can be removed to simplify rule.
+
+## rule/label
 
 This check works the same way as `annotation` check, but it operates on
 labels instead.
@@ -327,7 +337,7 @@ rule {
 }
 ```
 
-## Rate
+## promql/rate
 
 This check inspects `rate()` and `irate()` functions and warns if used duration
 is too low. It does so by first getting global `scrape_interval` value for selected
@@ -366,7 +376,7 @@ prometheus "dev" {
 }
 ```
 
-## Alerts
+## alerts/count
 
 This check is used to estimate how many times given alert would fire.
 It will run `expr` query from every alert rule against selected Prometheus
@@ -412,7 +422,7 @@ rule {
 }
 ```
 
-## Comparison
+## promql/comparison
 
 This check enforces use of a comparison operator in alert queries.
 Since any query result triggers an alert usual query would be something
@@ -422,7 +432,7 @@ and so it would always trigger an alert.
 
 This check is enabled by default and doesn't require any configuration.
 
-## Cost
+## query/cost
 
 This check is used to calculate cost of a query and optionally report an issue
 if that cost is too high. It will run `expr` query from every rule against
@@ -485,7 +495,7 @@ like memory pressure, Go version, GOGC settings etc.
 }
 ```
 
-## Series
+## query/series
 
 This check will also query Prometheus servers, it is used to warn about queries
 that are using metrics not currently present in Prometheus.
@@ -512,7 +522,7 @@ prometheus "prod" {
 }
 ```
 
-## Reject
+## rule/reject
 
 This check allows rejecting label or annotations keys and values
 using regexp rules.
@@ -565,7 +575,7 @@ rule {
 }
 ```
 
-## Template
+## alerts/template
 
 This check validates templating used in annotations and labels for alerting rules.
 See [Prometheus docs](https://prometheus.io/docs/prometheus/latest/configuration/template_reference/)
@@ -589,7 +599,7 @@ for more details.
 
 This check is enabled by default and doesn't require any configuration.
 
-## Vector Matching
+## promql/vector_matching
 
 This check will try to find queries that try to
 [match vectors](https://prometheus.io/docs/prometheus/latest/querying/operators/#vector-matching)
@@ -640,7 +650,7 @@ prometheus "prod" {
 }
 ```
 
-## Fragile
+## promql/fragile
 
 This check will try to find rules with queries that can be rewritten in a way
 which makes them more resilient to label changes.