search

grafana / oncall

Developer-friendly incident response with brilliant Slack integration
GNU Affero General Public License v3.0
3.44k stars 276 forks source link

Add doc-validator workflow #1224

Closed jdbaldry closed 1 year ago

jdbaldry commented 1 year ago

doc-validator codifies best practices for technical documentation at Grafana. Linting errors are defined in https://github.com/grafana/technical-documentation/blob/main/tools/cmd/doc-validator/errata.hcl.

The errors enumerated in the errata file are under active development and are intended to be helpful in explaining reasoning and fixes for linting issues.

Not all errors meet this goal yet, so please report any errors that are confusing, seem to lack motivation, or are hard to resolve.

Signed-off-by: Jack Baldry jack.baldry@grafana.com

joeyorlando commented 1 year ago

@jdbaldry we have a pre-commit step which runs markdownlint against ./docs. Would you recommend we turn that off in favour of these checks?

jdbaldry commented 1 year ago

Hey @joeyorlando, I'd say the two are complementary. doc-validator is more of a linter of technical documentation than of the Markdown itself.

jdbaldry commented 1 year ago

I need to fix some canonical front matter validation and then I will open this PR for review.

jdbaldry commented 1 year ago

I believe this is now ready for review. The errors reported by the validator can be seen in https://github.com/grafana/oncall/actions/runs/4232345624/jobs/7351966975 and will need fixing before this can be merged.

joeyorlando commented 1 year ago

does someone from @grafana/docs-oncall want to volunteer to patch these validation errors?

joeyorlando commented 1 year ago

@jdbaldry or @alyssawada did we want to merge this in?

jdbaldry commented 1 year ago

I can spend a half hour now trying to clean up the errors so we can merge this.

jdbaldry commented 1 year ago

I think I might need @alyssawada to work through the remaining errors. It requires that each document have a description set in the front matter. There's more information about our front matter requirements in https://grafana.com/docs/writers-toolkit/writing-guide/front-matter/ but I don't understand the content well enough to provide good descriptions myself.

joeyorlando commented 1 year ago

is this PR still relevant or should it be closed?

jdbaldry commented 1 year ago

I believe there has been a move away from having a technical writer on this project. This CI workflow requires a technical writer to fix the linting issues identified so I'll close this until there are resources to apply the fixes.