Health status documentation

[Bravo555]

Proposed changes

This PR updates the markdown documentation regarding health statuses and health checks.

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Improvement (general improvements like code refactoring that doesn't explicitly fix a bug or add any new functionality)
• Documentation Update (if none of the other choices apply)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Paste Link to the issue

• Document health status and health check messages #2348

Checklist

• I have read the CONTRIBUTING doc
• I have signed the CLA (in all commits with git commit -s)
• I ran cargo fmt as mentioned in CODING_GUIDELINES
• I used cargo clippy as mentioned in CODING_GUIDELINES
• I have added tests that prove my fix is effective or that my feature works
• I have added necessary documentation (if appropriate)

Further comments

[github-actions]

Robot Results

✅ Passed	❌ Failed	⏭️ Skipped	Total	Pass %	⏱️ Duration
344	0	4	344	100	53m22.164s

[rina23q]

Good work! A bit more needs to be updated

[albinsuresh]

Sorry, was a bit late to submit my review. But there are some mistakes in the updated docs, that you'd have to correct.

[albinsuresh]

Although I agree that this looks better, we're not sure if these reformattings are sustainable. Every time we add a new entry or update an existing entry, like Description, a similar reformatting will be required affecting all the lines. That's why we went for the easiest, maintainable option.

[Bravo555]

I agree, I'll disable my markdown formatting extensions and try to not reformat stuff in the future.

[albinsuresh]

Suggested change

	| status | Service status |
	| status | Entity status |

[Bravo555]

AFAIK currently we have only services publishing health status messages, and this status category is not clearly defined:

• can health status messages be published for devices as well?
• are there any other statuses valid for devices but not services?

I think this status category is only referenced here, so I'd rather be conservative with the wording here and only describe what is currently implemented, instead of trying to cover how it might be implemented in the future.

[albinsuresh]

What do you mean?

[Bravo555]

See this comment: #2375 (comment)

IMO we have a lot of repetition going on between different documentation pages, where a lot of the properties of different messages are mentioned in different contexts, and we should be aiming to have a reference describing these things in a single place.
Here, I don't think this table of properties of a health message doesn't add much value, as we don't refer to pid or time much in the rest of this document, but it's tricky where to draw the line which things are better to be extracted, and which be duplicated for the convenience of the reader.