recording_rules page is confusing

[jpds]

The page at: https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/ is somewhat unclear:

1. It shows an example rules file
2. Immediately goes to <rule_group> where there should be an accompanying explanation (also loses the indentation).
3. Shows a <rule> example which seems to suggest that record is a required field (not in [])
4. Then an alert example is shown where (the required) record is gone and replaced with alert
5. The alert example has the commment: # The name of the alert. Must be a valid metric name. - but these are usually strings like HighErrorRate, not metrics.

[andrechalella]

Yes. Also lots of info that pertain to "Alerting rules" are in the "Recording rules" page. IMO, since both pages are relatively small and have so much in common, they should be merged.