check information in README.md and other docs should be programmatically generated from checks.md

[laurentsimon]

An internal team complained that the description in https://github.com/ossf/scorecard#scorecard-checks is different from those in checks.md (Packaging check)

We should pull all the doc for checks from checks.yaml and generate the section of the README programatically. We now have a short field in the checks.md that we may be able to re-use (does not support clickable links, though).

More generally, anywhere we refer to checks, we should generate that programatically.

[laurentsimon]

note that in checks/* (registerCheck()) we could also retrieve the check names from the yaml file

[laurentsimon]

the run examples should also be generated programatically.

[naveensrinivasan]

the run examples should also be generated programatically.

Can you please explain further on run examples?

[laurentsimon]

oops, sorry.. that was vague. Ideally https://github.com/ossf/scorecard#using-repository-url would be generated from a scorecard run to generate the output example. I don't know how feasible this is in practice.

[laurentsimon]

another thing we need to fix: We tend to update checks' source code but forget to update the checks' documentation in the same PR. We need to catch this. One idea would be to:

1. Create a tool that we run during PR validation in a workflow
2. The tool would check if anything changes under checks/.
   2.1 If something changed under checks/ and the doc was updated, PASS.
   2.2 If something changed under checks/ but the doc was not updated, FAIL, unless the PR is tagged with a label, say no-doc-change-needed. Reviewers can add the label after reviewing the PR.

In addition to the above, we could also add Need doc update in the PR template to inform the reviewer.

WDUT?

[laurentsimon]

we can do the same for keep the cron section of the readme up-to-date, by monitoring changes under cron/

[github-actions]

Stale issue message

[lasomethingsomething]

Reviewed in community backlog -- would be automatically update docs with explanations about how scorecard works. Impact of not having this is that docs may be different in the Readme vs. the output. Primary value here would be to reduce toil for the maintainers so they no longer have to update docs in two places.