Improve heartbeat http monitor docs
- Dominant language
- Go
- Stars
- 12.7k
- Forks
- 5k
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 364
Description
The [documentation for the HTTP monitors for Heartbeat](https://www.elastic.co/docs/reference/beats/heartbeat/monitor-http-options#monitor-http-check) are a bit hard to follow due to their format.
**The headers in the doc do not appear to be correct.**
Everything starts out as H3 and then “headers” and “response” are H2. This is not so bad on its own but really hurts the side nav.
**The doc has “check” nested under “response”**
“response” and “request” are nested under “check” when you define it in the YAML. ( ex. check.request or check.response ). The bigger benefit I think you would get from nesting everything under "check" using headers would be an easier to read and navigate document. Right now the docs just have “check” as an anchor and then “check.response” in plain text. Then there are definitions for each “feature” under check response. Since the “features” ( ex. method, headers, body ) are definitions and not H4, it doesn’t show up in the side navigation. It also makes the doc difficult to follow. Updating each section to be a nested heading would create a structure under “check” that a user would be able to walk down ( ex. check -> response -> json -> description ).
**As an example $.[0].foo == "bar" tests that the first item in the response has an attribute foo that has the value "bar".**
$.[0].foo does not seem to work when an array is the root. $[0].foo did work. In my case, the array being returned was an array of objects. I didn't have a great way to quickly test out different response bodies. Wanted to mention this in case this was incorrect.
Contributor guide
Research direction
Start with the linked Heartbeat HTTP monitor documentation and inspect the heading hierarchy around check, request, and response, including the YAML examples and response-expression guidance. Restructure the headings so the side navigation reflects the documented nesting, then verify whether the root-array expression example is correct and update the documentation accordingly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json, yaml
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 73/100